Source: https://primereact.org/dropdown/

Introducing PrimeReact v11 Alpha 🥁Learn More

• SearchK

• 10.9.7

  • v11(11.0.0)

  • v10(10.9.7)

  • v9(9.6.3)

• FEATURES

• API

• THEMING

• PASS THROUGH

Dropdown

Dropdown also known as Select, is used to choose an item from a collection of options.

Import#

---

import { Dropdown } from 'primereact/dropdown';
         

Copy

Basic#

---

Dropdown is used as a controlled component with value and onChange properties along with an options collection. Label and value of an option are defined with the optionLabel and optionValue properties respectively. Default property name for the optionLabel is label and value for the optionValue. If optionValue is omitted and the object has no value property, the object itself becomes the value of an option. Note that, when options are simple primitive values such as a string array, no optionLabel and optionValue would be necessary.

Select a City

Select a City

<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    placeholder="Select a City" className="w-full md:w-14rem" />
         

Copy

Checkmark#

---

An alternative way to highlight the selected option is displaying a checkmark instead.

Select a City

Select a City

<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    placeholder="Select a City" className="w-full md:w-14rem" checkmark={true}  highlightOnSelect={false} />
         

Copy

Editable#

---

When editable is present, the input can also be entered with typing.

Select a City

<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    editable placeholder="Select a City" className="w-full md:w-14rem" />
         

Copy

Group#

---

Options can be grouped when a nested data structures is provided. To define the label of a group optionGroupLabel property is needed and also optionGroupChildren is required to define the property that refers to the children of a group.

Select a City

Select a City

<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={groupedCities} optionLabel="label" 
    optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} className="w-full md:w-14rem" placeholder="Select a City" />
         

Copy

Template#

---

Options and the selected option display support templating with itemTemplate and valueTemplate properties respectively.

Select a Country

Select a Country

<Dropdown value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" placeholder="Select a Country" 
    valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} className="w-full md:w-14rem" panelFooterTemplate={panelFooterTemplate}
    dropdownIcon={(opts) => {
        return opts.iconProps['data-pr-overlay-visible'] ? <ChevronRightIcon {...opts.iconProps} /> : <ChevronDownIcon {...opts.iconProps} />;
    }} 
/>
         

Copy

Filter#

---

Dropdown provides built-in filtering that is enabled by adding the filter property.

Select a Country

Select a Country

<Dropdown value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" placeholder="Select a Country" 
    filter valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} className="w-full md:w-14rem" />
         

Copy

Clear Icon#

---

When showClear is enabled, a clear icon is added to reset the Dropdown.

Select a City

Select a City

<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    showClear placeholder="Select a City" className="w-full md:w-14rem" />
         

Copy

Loading State#

---

Loading state can be used loading property.

Loading...

Loading...

<Dropdown loading placeholder="Loading..." className="w-full md:w-14rem" />
         

Copy

Virtual Scroll#

---

VirtualScroller is used to render a long list of options efficiently like 100K records in this demo. The configuration is done with virtualScrollerOptions property, refer to the VirtualScroller for more information about the available options as it is used internally by Dropdown.

Select Item

Select Item

<Dropdown value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} virtualScrollerOptions={{ itemSize: 38 }} 
    placeholder="Select Item" className="w-full md:w-14rem" />
         

Copy

Lazy Virtual Scroll#

---

Select Item

Select Item

<Dropdown value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} virtualScrollerOptions={{ itemSize: 38 }} 
    placeholder="Select Item" className="w-full md:w-14rem" />
         

Copy

Float Label#

---

A floating label appears on top of the input field when focused.

 Select a City

<FloatLabel>
    <Dropdown inputId="dd-city" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full" />
    <label htmlFor="dd-city">Select a City</label>
</FloatLabel>
         

Copy

Filled#

---

Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.

Select a City

Select a City

<Dropdown variant="filled" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    placeholder="Select a City" className="w-full md:w-14rem" />
         

Copy

Invalid#

---

Invalid state is displayed using the invalid prop to indicate a failed validation. You can use this style when integrating with form validation libraries.

Select a City

Select a City

<Dropdown invalid value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    placeholder="Select a City" className="w-full md:w-14rem" />
         

Copy

Disabled#

---

When disabled is present, the element cannot be edited and focused.

Select a City

Select a City

<Dropdown disabled placeholder="Select a City" className="w-full md:w-14rem" />
         

Copy

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

Copy

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

• Import

• Basic

• Checkmark

• Editable

• Group

• Template

• Filter

• Clear Icon

• Loading State

• Virtual Scroll

• Lazy Virtual Scroll

• Float Label

• Filled

• Invalid

• Disabled

• Accessibility

PrimeReact 10.9.7 by PrimeTek