ComboBox is the combination of a Textfield and an associated Dropdown that allows the user to filter a list when selecting an option. ComboBox allows users to type the full option, type part of the option and narrow the results, or select an option from the list.
Note: this is a new version of the deprecated component "Typeahead".
ComboBox requires both
accessibilityClearButtonLabel. By default, the
label is visible above TextField. However, if the form items are labeled by content elsewhere on the page, or a more complex label is needed, the
labelDisplay prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen.
In the example below, the "Discover this week's top searched trends across all categories" text is acting as a heading, so instead of repeating another label, we visually hide the label. When a user focuses on the ComboBox, a screen reader will announce "Choose a category to display top search trends, Select category".
Spacekey on the ComboBox's trigger opens the options list
- Once an item is selected, hitting
Spaceon the clear button clears the selection and returns focus to the input textfield
Escapekey closes the options list, while moving focus back on the ComboBox's trigger
- Arrow keys are used to navigate items within the options list
Enterkey selects an item within the options list
Shift + Tabclose the options list and move focus accordingly
Be sure to localize the
value should be localized for those cases that can be translated. Note that localization can lengthen text by 20 to 30 percent.
Controlled vs Uncontrolled
ComboBox can be used as a controlled or an uncontrolled component. An uncontrolled ComboBox stores its own state internally and updates it based on the user input. On the other side, a controlled ComboBox's state is managed by a parent component. The parent component's state passes new values through props to the controlled component which notifies changes through event callbacks.
An uncontrolled ComboBox should be used for basic cases where no default value or tags are required. Don't pass
selectedOptions props to keep the component uncontrolled. By passing
inputValue to ComboBox, the component fully manages its internal state: any value different from
undefined makes Combobox controlled.
A controlled ComboBox is required if a selected value is set, as shown in the first example. In the second example, values are set programatically. Controlled Comboboxes with tags are also controlled components. A controlled ComboBox requires three value props:
selectedOptions. ComboBox is notified of changes via the
onClear props. All values displayed by ComboBox at any time are controlled externally. To clear
inputValue, set the value to an empty string
undefined values turn ComboBox into an uncontrolled component.
Include Tag elements in the input using the
Note that the
ComboBox component doesn't internally manage tags; therefore, it must be a controlled component. A controlled ComboBox requires three value props:
To use ComboBox with tags, it's recommended to create new tags on enter key presses, to remove them on backspaces when the cursor is in the beginning of the field and to filter out empty tags. These best practices are shown in the following example.
To control focus or position and anchor components to ComboBox, use
ref as shown in the examples below.
subtext under each selection option
If users need to select from a short, simple list (without needing sections, subtext details, or the ability to filter the list), use SelectList.
Dropdown is an element constructed using Popover as its container. Use Dropdown to display a list of actions or options in a Popover.
Use Fieldset to group related form items.