Dropdown also known as Select, is used to choose an item from a collection of options.
import { Dropdown } from 'primereact/dropdown';
SelectButton is used as a controlled component with value and onChange properties along with the options collection. There are two alternatives of how to define the options property; One way is providing a collection of SelectItem instances having label-value pairs whereas other way is providing an array of arbitrary objects along with the optionLabel and optionValue properties to specify the label/value field pair. In addition, options can be simple primitive values such as a string array, in this case no optionLabel or optionValue is necessary.
<Dropdown value={selectedCity} options={cities} onChange={onCityChange} optionLabel="name" placeholder="Select a City" />
SelectButton is used as a controlled component with value and onChange properties along with the options collection. There are two alternatives of how to define the options property; One way is providing a collection of SelectItem instances having label-value pairs whereas other way is providing an array of arbitrary objects along with the optionLabel and optionValue properties to specify the label/value field pair. In addition, options can be simple primitive values such as a string array, in this case no optionLabel or optionValue is necessary.
<Dropdown value={selectedCity} options={cities} onChange={onCityChange} optionLabel="name" editable />
Options groups are specified with the optionGroupLabel and optionGroupChildren properties.
<Dropdown value={selectedGroupedCity} options={groupedCities} onChange={onGroupedCityChange} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} />
A floating label is implemented by wrapping the input and the label inside a container having .p-float-label style class.
<Dropdown inputId="dropdown" value={value} options={cities} onChange={(e) => setValue(e.value)} optionLabel="name" />
<label htmlFor="dropdown">Dropdown</label>
<Dropdown inputId="dropdown" value={value} options={cities} onChange={(e) => setValue(e.value)} optionLabel="name" className='p-invalid'/>
<label htmlFor="dropdown">Dropdown</label>
<Dropdown className="p-disabled" />
<label htmlFor="dropdown">Dropdown</label>
<Dropdown value={selectedCountry} options={countries} onChange={onCountryChange} optionLabel="name" placeholder="Select a Country" valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />
<Dropdown value={selectedCountry} options={countries} onChange={onCountryChange} optionLabel="name" filter filterBy="name" placeholder="Select a Country" valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />
<Dropdown value={selectedCountry} options={countries} onChange={onCountryChange} optionLabel="name" showClear placeholder="Select a Country" valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />
<Dropdown value={selectedItem} options={items} onChange={onItemChange} virtualScrollerOptions={{ itemSize: 38 }} placeholder="Select Item"/>
<Dropdown value={selectedItem} options={items} onChange={onItemChange} virtualScrollerOptions={{ itemSize: 38 }} placeholder="Select Item"/>
Formik is a popular library for handling forms in React.
<Toast ref={toast} />
<Dropdown
inputId="city"
name="city"
value={formik.values.city}
options={cities}
optionLabel="name"
placeholder="Select a City"
onChange={(e) => {
formik.setFieldValue('city', e.value);
}}
/>
{getFormErrorMessage('city')}
<Button type="submit" label="Submit" />
React Hook Form is another popular React library to handle forms.
<Toast ref={toast} />
<Controller
name="city"
control={control}
rules={{ required: 'City is required.' }}
render={({ field, fieldState }) => (
<Dropdown
value={field.value}
optionLabel="name"
placeholder="Select a City"
name="city"
options={cities}
control={control}
onChange={(e) => field.onChange(e.value)}
className={classNames({ 'p-invalid': fieldState.error })}
/>
)}
/>
{getFormErrorMessage('city')}
<Button type="submit" label="Submit" />
Following is the list of structural style classes, for theming classes visit theming page.
Name | Element |
---|---|
p-dropdown | Container element. |
p-dropdown-label | Element to display label of selected option. |
p-dropdown-trigger | Icon element. |
p-dropdown-panel | Icon element. |
p-dropdown-items-wrapper | Wrapper element of items list. |
p-dropdown-items | List element of items. |
p-dropdown-item | An item in the list. |
p-dropdown-filter-container | Container of filter input. |
p-dropdown-filter | Filter element. |
p-dropdown-open | Container element when overlay is visible. |
Value to describe the component can either be provided with aria-labelledby or aria-label props. The dropdown element has a combobox role in addition to aria-haspopup and aria-expanded attributes. If the editable option is enabled aria-autocomplete is also added. The relation between the combobox and the popup is created with aria-controls and aria-activedescendant attribute is used to instruct screen reader which option to read during keyboard navigation within the popup list.
The popup list has an id that refers to the aria-controls attribute of the combobox element and uses listbox as the role. Each list item has an option role, an id to match the aria-activedescendant of the input element along with aria-label, aria-selected and aria-disabled attributes.
If filtering is enabled, filterInputProps can be defined to give aria-* props to the filter input element.
<span id="dd1">Options</span>
<Dropdown aria-labelledby="dd1" />
<Dropdown aria-label="Options" />
Key | Function |
---|---|
tab | Moves focus to the dropdown element. |
space | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
down arrow | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
up arrow | Opens the popup and moves visual focus to the selected option, if there is none then last option receives the focus. |
Key | Function |
---|---|
tab | Moves focus to the next focusable element in the popup, if there is none then first focusable element receives the focus. |
shift + tab | Moves focus to the previous focusable element in the popup, if there is none then last focusable element receives the focus. |
enter | Selects the focused option and closes the popup. |
space | Selects the focused option and closes the popup. |
escape | Closes the popup, moves focus to the dropdown element. |
down arrow | Moves focus to the next option, if there is none then visual focus does not change. |
up arrow | Moves focus to the previous option, if there is none then visual focus does not change. |
right arrow | If the dropdown is editable, removes the visual focus from the current option and moves input cursor to one character left. |
left arrow | If the dropdown is editable, removes the visual focus from the current option and moves input cursor to one character right. |
home | If the dropdown is editable, moves input cursor at the end, if not then moves focus to the first option. |
end | If the dropdown is editable, moves input cursor at the beginning, if not then moves focus to the last option. |
any printable character | Moves focus to the option whose label starts with the characters being typed if dropdown is not editable. |
Key | Function |
---|---|
enter | Closes the popup and moves focus to the dropdown element. |
escape | Closes the popup and moves focus to the dropdown element. |