Example
On mobile devices, Combobox automatically displays in a tray instead of a popover to improve usability.
Patterns
Collections
Combobox implements react-stately collection components, <Item> and <Section>.
Static collections, seen in the example above, can be used when the full list of options is known ahead of time.
Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time. Providing the data in this way allows the combobox to cache the rendering of each item, which improves performance.
Keys and IDs
Dynamic collections provide an iterable list of items to the combobox. Each item accepts a unique key prop, which is passed to the onSelectionChange handler to identify the selected item.
If the item objects contain an id property, as shown in the example above, then this is used automatically and a key prop is not required.
Sections
Use the <Section> component to group related items. Each Section takes a title and key prop.
Sections used with dynamic items are populated from a hierarchical data structure. Similar to the combobox itself, Section takes an array of data using the items prop.
Selection
Setting a selected item can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the key of an item, where "id" is used by default.
See the react-stately selection docs for more information.
Controlled
Use the selectedKey the control the value of the combobox and watch for changes with the onSelectionChange handler, which accepts the selected item’s key as its only argument.
Uncontrolled
Use the defaultSelectedKey prop for uncontrolled cases.
Slots
Icons and descriptions can be added as children of an item, to better communicate the effect of each option’s selection. If a description is added, the prop slot="description" must be used to distinguish it from the primary <Text> label.
Extra visual details increase the cognitive load on users. Include additional elements only when it improves clarity and will contribute positively to the understanding of an interface.
Props
Label
Combobox should be labelled using the label prop. If a visible label isn’t appropriate, use the aria-label prop to identify the control for accessibility.
Disabled
A combobox that isDisabled shows that a field exists, but is not currently available.
You can also provide disabledKeys to limit selection.
Read only
The isReadOnly prop makes a field’s value immutable. Unlike isDisabled, the field remains focusable and the contents can still be copied.
Required
A combobox can be marked as required by setting the isRequired prop.
Description
The description communicates a hint or helpful information, such as specific requirements for what to choose.
Error message
The errorMessage communicates an error when the selection requirements aren’t met, prompting the user to adjust what they had originally selected.
Custom width
The menu will assume the width of the invoking trigger.
Direction
The menu will “flip” when there isn’t enough space to render below the trigger, by default. You can force the menu’s opening direction in cases where it should always render above.