React Dropdown

React Dropdown is used to select an item from a collection of options.

Setup

Refer to PrimeReact setup documentation for download and installation steps for your environment.

Import

import { Dropdown } from 'primereact/dropdown';

Getting Started

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.

Options as SelectItems

const citySelectItems = [
    {label: 'New York', value: 'NY'},
    {label: 'Rome', value: 'RM'},
    {label: 'London', value: 'LDN'},
    {label: 'Istanbul', value: 'IST'},
    {label: 'Paris', value: 'PRS'}
];

<Dropdown value={city} options={citySelectItems} onChange={(e) => setCity(e.value)} placeholder="Select a City"/>

Options as any type

const cities = [
    {name: 'New York', code: 'NY'},
    {name: 'Rome', code: 'RM'},
    {name: 'London', code: 'LDN'},
    {name: 'Istanbul', code: 'IST'},
    {name: 'Paris', code: 'PRS'}
];

<Dropdown optionLabel="name" value={city} options={cities} onChange={(e) => setCity(e.value)} placeholder="Select a City"/>
<Dropdown optionLabel="name" optionValue="code" value={city} options={cities} onChange={(e) => setCity(e.value)} placeholder="Select a City"/>

When optionValue is not defined, value of an option refers to the option object itself.

Placeholder

Common pattern is providing an empty option as the placeholder when using native selects, however Dropdown has built-in support using the placeholder option so it is suggested to use it instead of creating an empty option.

Filtering

Options can be filtered using an input field in the overlay by enabling the filter property. By default filtering is done against label of the items and filterBy property is available to choose one or more properties of the options. In addition filterMatchMode can be utilized to define the filtering algorithm, valid options are "contains" (default), "startsWith", "endsWith", "equals" and "notEquals".

<Dropdown value={selectedCountry} options={countries} onChange={(e) => setSelectedCountry(e.value)} optionLabel="name" filter showClear filterBy="name"
    placeholder="Select a Country" itemTemplate={countryOptionTemplate} />

Custom Content

Label of an option is used as the display text of an item by default, for custom content support define an itemTemplate function that gets the option instance as a parameter and returns the content.

<Dropdown value={selectedCountry} options={countries} onChange={(e) => setSelectedCountry(e.value)} optionLabel="name" placeholder="Select a Country"
    valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} />

const selectedCountryTemplate = (option, props) => {
    if (option) {
        return (
            <div className="country-item country-item-value">
                <img alt={option.name} src="showcase/demo/images/flag_placeholder.png" className={`flag flag-${option.code.toLowerCase()}`} />
                <div>{option.name}</div>
            </div>
        );
    }

    return (
        <span>
            {props.placeholder}
        </span>
    );
}

const countryOptionTemplate = (option) => {
    return (
        <div className="country-item">
            <img alt={option.name} src="showcase/demo/images/flag_placeholder.png" className={`flag flag-${option.code.toLowerCase()}`} />
            <div>{option.name}</div>
        </div>
    );
}

Theming

Dropdown supports various themes featuring Material, Bootstrap, Fluent as well as your own custom themes via the Designer tool.

Resources

Visit the PrimeReact Dropdown showcase for demos and documentation.