ComboBox

ComboBoxes combine a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query.

Example#

Content#

ComboBox follows the Collection Components API, accepting both static and dynamic collections. Similar to Picker, ComboBox accepts <Item> elements as children, each with a key prop. Basic usage of ComboBox, seen in the example above, shows multiple options populated with a string. Static collections, as in this example, 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 ComboBox to automatically cache the rendering of each item, which dramatically improves performance.

As seen below, an iterable list of options is passed to the ComboBox using the defaultItems prop. Each item accepts a key prop, which is passed to the onSelectionChange handler to identify the selected item. Alternatively, if the item objects contain an id property, as shown in the example below, then this is used automatically and a key prop is not required. See the Events section for more detail on selection.

Alternatively, passing your list of options to ComboBox's items prop will cause the list of items to be controlled, useful for when you want to provide your own filtering logic. See the Custom Filtering section for more detail.

Trays#

On mobile, ComboBox automatically displays in a tray instead of a popover to improve usability. The tray contains a search field that mobile users can use to filter the options available via text.

Internationalization#

To internationalize a ComboBox, a localized string should be passed to the children of each Item. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ComboBox is automatically flipped.

Value#

A ComboBox's value is empty by default, but an initial, uncontrolled, value can be provided using the defaultInputValue prop. Alternatively, a controlled value can be provided using the inputValue prop. Note that the input value of the ComboBox does not affect the ComboBox's selected option. See Events for more details on input change events.

Placeholder text that describes the expected value or formatting for the ComboBox can be provided using the placeholder prop. Placeholder text will only appear when the ComboBox is empty, and should not be used as a substitute for labeling the component with a visible label.

Custom Value#

By default on blur, a ComboBox will either reset its input value to match the selected option's text or clear its input value if an option has not been selected yet. If you would like to allow the end user to provide a custom input value to the ComboBox, the allowsCustomValue prop can be used to override the above behavior.

Labeling#

ComboBox can be labeled using the label prop. If the ComboBox is a required field, the isRequired and necessityIndicator props can be used to show a required state.

Accessibility#

If a visible label isn't specified, an aria-label must be provided to the ComboBox for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

In order to internationalize a ComboBox, a localized string should be passed to the label or aria-label prop. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Selection#

Setting a selected option can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the key of an item. See Events for more details on selection events. Additionally, see the react-stately Selection docs for caveats regarding selection prop typing.

Sections#

ComboBox supports sections in order to group options. Sections can be used by wrapping groups of items in a Section element. Each Section takes a title and key prop.

Static items#

Dynamic items#

Sections used with dynamic items are populated from a hierarchical data structure. Please note that Section takes an array of data using the items prop only.

Events#

ComboBox supports selection via mouse, keyboard, and touch. You can handle all of these via the onSelectionChange prop. ComboBox will pass the selected key to the onSelectionChange handler. Additionally, ComboBox accepts an onInputChange prop which is triggered whenever the value is edited by the user, whether through typing or option selection.

The example below uses onSelectionChange and onInputChange to update the selection and input value stored in React state.

Fully controlled ComboBox#

When a ComboBox has multiple controlled properties (e.g.inputValue, selectedKey, items), it is important to note that an update to one of these properties will not automatically update the others. Each interaction done in the ComboBox will only trigger its associated event handler. For example, typing in the field will only trigger onInputChange whereas selecting an item from the ComboBox menu will only trigger onSelectionChange so it is your responsibility to update the other controlled properties accordingly. Note that you should provide an onSelectionChange handler for a ComboBox with controlled input value and open state. This way, you can properly control the menu's open state when the user selects an option or blurs from the field.

The below example demonstrates how you would construct the same example above in a completely controlled fashion.

Complex items#

Items within ComboBox also allow for additional content used to better communicate options. Icons and descriptions can be added to the children of Item as shown in the example below. If a description is added, the prop slot="description" must be used to distinguish the different <Text> elements.

Asynchronous loading#

ComboBox supports loading data asynchronously, and will display a progress circle reflecting the current load state, set by the loadingState prop. It also supports infinite scrolling to load more data on demand as the user scrolls, via the onLoadMore prop.

This example uses the useAsyncList hook to handle loading the data. See the docs for more information.

When both inputValue and selectedKey are controlled, and the selectedKey is set to an initial value before the items load, you must update the inputValue when the items load. This can be done by returning filterText from the useAsyncList load function.

The example below demonstrates how you could update the input value for your selected key once your list of items has been fetched.

Validation#

ComboBox can display a validation state to communicate to the user whether the current value is valid or invalid. Implement your own validation logic in your app and pass either "valid" or "invalid" to the ComboBox via the validationState prop.

The example below illustrates how one would validate if the user has entered a valid email into the ComboBox.

Custom Filtering#

By default, ComboBox uses a string "contains" filtering strategy when deciding what items to display in the dropdown menu. This filtering strategy can be overwritten by filtering the list of items yourself and passing the filtered list to the ComboBox via the items prop.

The example below uses a string "startsWith" filter function obtained from the useFilter hook to display items that start with the ComboBox's current input value only. By using the menuTrigger returned by onOpenChange, it also handles displaying the entire option list regardless of the current filter value when the ComboBox menu is opened via the trigger button or arrow keys. menuTrigger tells you if the menu was opened manually by the user ("manual"), by focusing the ComboBox ("focus"), or by changes in the input field ("input"), allowing you to make updates to other controlled aspects of your ComboBox accordingly.

Trigger options#

By default, the ComboBox's menu is opened when the user types into the input field ("input"). There are two other supported modes: one where the menu opens when the ComboBox is focused ("focus") and the other where the menu only opens when the user clicks or taps on the ComboBox's field button ("manual"). These can be set by providing "focus" or "manual" to the menuTrigger prop. Guidelines on when to use a specific mode can be found here. Note that the mobile ComboBox experience requires the end user to press the ComboBox button to open the tray regardless of the menuTrigger setting.

Props#

Visual options#

Label alignment and position#

View guidelines

By default, the label is positioned above the ComboBox. The labelPosition prop can be used to position the label to the side. The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the ComboBox and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

Quiet#

View guidelines

Disabled#

View guidelines

Read only#

View guidelines

Help text#

View guidelines

Both a description and an error message can be supplied to a ComboBox. The description is always visible unless the validationState is “invalid” and an error message is provided. The error message can be used to help the user fix their input quickly and should be specific to the detected error. All strings should be localized.

Custom widths#

View guidelines

Menu direction#