React Select Component

Import#


import { Dropdown } from 'primereact/dropdown';

Basic#

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" />

Editable#

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 />

Grouped#

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} />

Float Label#

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>

Invalid#


<Dropdown inputId="dropdown" value={value} options={cities} onChange={(e) => setValue(e.value)} optionLabel="name" className='p-invalid'/>
<label htmlFor="dropdown">Dropdown</label>

Disabled#


<Dropdown className="p-disabled" />
<label htmlFor="dropdown">Dropdown</label>

Template#


<Dropdown value={selectedCountry} options={countries} onChange={onCountryChange} optionLabel="name" placeholder="Select a Country" valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />

Filter#


<Dropdown value={selectedCountry} options={countries} onChange={onCountryChange} optionLabel="name" filter  filterBy="name" placeholder="Select a Country" valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />

Clear Icon#


<Dropdown value={selectedCountry} options={countries} onChange={onCountryChange} optionLabel="name" showClear placeholder="Select a Country" valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />

Virtual Scroll#

Whether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.

Eager#


<Dropdown value={selectedItem} options={items} onChange={onItemChange} virtualScrollerOptions={{ itemSize: 38 }} placeholder="Select Item"/>

Lazy#


<Dropdown value={selectedItem} options={items} onChange={onItemChange} virtualScrollerOptions={{ itemSize: 38 }} placeholder="Select Item"/>

Form#

Compatibility with popular React form libraries.

Formik#

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" />

Hook Form#

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" />

Style#

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.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

Accessibility#

Screen Reader

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" />

Closed State Keyboard Support

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.

Popup Keyboard Support

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.

Filter Input Keyboard Support

Key	Function
enter	Closes the popup and moves focus to the dropdown element.
escape	Closes the popup and moves focus to the dropdown element.

API#

Visit the API documentation for detailed information about all the properties, events and methods of the component.

Dropdown