Skip to main content

Dropdowns Components

A set of <select> alternatives, and autocomplete components, Dropdowns map a selection from list of options or suggestions to a form value. These components may represent a single value or an array values. They may limit selection to only list options or allow free text.

React widgets has three dropdown components: <Combobox>, <DropdownList>, and <Multiselect> each share a large amount of functionality but are designed to meet specific use-cases.

<Combobox> is a traditional "autocomplete" or "type ahead" component. Its value may be any text but suggestions are provided for cases where a more structured option is available.

The <DropdownList>, only allows values selected from its options list. It's a direct alternative to the <select>. The <Multiselect> is similar but represents an array of values selected from the options list instead of one (like <select multiple>).


Each dropdown component accepts a data prop for providing the dropdown options.

data items are not limited to strings or numbers. When an option is selected, or a typed value matches the text of a data item it will be used as the value of the input in order to provide richer context for the selection.

{ id: 1, color: "Red" },
{ id: 2, color: "Yellow" },
{ id: 3, color: "Blue" },
{ id: 4, color: "Orange" },

Note that textField tells the input how to display the selected item. dataKey can also be used to help differentiate values from each other and not rely on strict equality between data items.

Selecting a value#

Components share a similar API to native DOM inputs in React. They each accept a value prop as well as an onChange handler for listening to value changes.

These props can be controlled in order to push state higher up the component tree.

You can also leave the value uncontrolled, and provide an initial default with defaultValue.

Mapping complex data to simple values#

The value prop can any item in data or any dataKey for complex options. The component will automatically resolve a value to its data item if it exists.

Heads Up

Regardless of whether value is a key or a data item, onChange will pass back the data item if it exists, not the value at dataKey.

Toggling the dropdown menu#

Like value, the open state of a dropdown component can be controlled by a parent component.

Custom Rendering#

List options can customize how they are rendered via the renderListItem prop

The <DropdownList> and <Multiselect> also have props for customizing value or selected tags.

Asynchronous data fetching#

Actually fetching data is outside the scope of react widgets, but components provide simple hooks for loading data. The busy prop provides visual loading feedback, and can be customized with the busySpinner prop.

Combine with the some React state to asynchronously load data to