A single item can be selected from the combo box options.

ComboBox contains an input field that opens a list. As users type, the list displays all filtered options based on their input.

• You can wrap ComboBox in a FormField when it’s displayed within a form context. This provides functionality built into Form Field for increased accessibility. For more information, refer to the FormField guidance.

When multiselect={true}, users can select multiple items from the combo box options. Selected options are displayed as pills in the input field.

You can use a placeholder to prompt user input if no default value is provided.

Never use placeholder text to provide the user with contextual help. It will be removed when the user starts typing and it does not meet minimum contrast requirements. Doing so is a WCAG failure.

Instead, use FormFieldHelperText beneath the field to provide instructions or directions which are necessary to complete the field, and reserve the placeholder text to support the help message, or provide an example of the suggested content.

More information can be found in the W3C form instructions.

The component has two variants: primary and secondary. The primary variant is set by default. Set to secondary with variant=”secondary”.

The choice between primary and secondary variants should be considered alongside the background color it sits upon.

The forms pattern provides further guidance on primary versus secondary control selection. You can wrap ComboBox in a FormField when it’s displayed within a orm context. This provides functionality built into FormField for increased accessibility. For more information, refer to the FormField guidance.

You can disable the combo box if required, for instance if the access to the options needs to be restricted based on the current context.

Unlike read-only, the disabled state can change for the current user depending on context. Showing it in a disabled state allows the user to be aware of the presence of the control, without enabling access to its functionality temporarily.

When disabled={true}, user will not be able to interact with combo box. It does not receive focus on any interaction.

Set the combo box to read-only to allow values to be displayed that are predefined and not editable, for instance when a user does not have the appropriate permissions to select an option within the combo box.

When readOnly={true} users will not be able to interact with combo box apart from focusing on it. Use to indicate that the pre-selected value is valid but changes are not permitted.

Use the disabled prop on the Option component to disable an option. Disabled options are not selectable and are visually distinct from selectable options.

Wrap ComboBox in a FormField to make it accessible within a form. This will provide the combo box with a visible label, help text and a status message for validation feedback. More information can be found in the W3C form instructions.

Wrap options in a OptionGroup component to group them together. Use the label prop to provide a label for the group.

To display a message when there are no options available, pass your message as a child element with role="option".

You can supply static content as children to the Option component. This can be used to visually assist users, for example rendering the flag icons next to the name of countries or to provide descriptions for additional context as seen in this example.

• Users can benefit from seeing a particular visual with list items. Customize the display as you see fit. For example, if displaying a list of contacts, it may help to provide headshots alongside the option text.
• Place any visual support such as icons, country symbols or avatars to the left of the option text.
• Give users a quicker and easier experience when they’re choosing their options by changing the logic of the component’s typeahead filter.

ComboBox can show validation states (warning, success, error) with the prop validationStatus.

• Use the error state to alert the user of a critical issue that’s related to the input. This issue, which may jeopardize completion of the task, usually requires action from the user to resolve the error.
• Display the warning state when you need to alert the user of a potential issue—that won’t prevent the user from continuing with the task, but may cause errors if it’s not addressed.

Due to its flexible API, you can customize the filtering logic ComboBox uses to suit your needs. In this example it displays the entire list of options when the combo box opens due to a mouse click.

You can use ComboBox to display data from a server. In this example, a list of states is fetched from a JSON file and filtered on the client side.

Note that the data fetching in this example has been made intentionally slow to highlight the loading states.

In order to support advanced use-cases, like where the options are fetched from a server, the value prop passed to Option can be an object. When the value prop is an object, the valueToString prop must be provided to ComboBox to specify how to display the option in the input field.

Use the truncate prop when you are limited on space and want to prevent the multi-select combobox from spanning multiple lines.

Use the selectOnTab prop to select the active option from the list on Tab key press.

In order to clear all the selections, you can pass a Button to the endAdornment prop of the ComboBox.

To style ComboBox with a full border, set bordered={true}.

We recommend this styling when the field uses the same fill color as the background (i.e., a primary fill color on a primary background).

If users need to select an option not in a predefined list, use a controlled ComboBox and add an Option to the bottom of the list matching the typed-in text.

This functionality allows users to input information that might not be covered by the provided choices, offering flexibility and accommodating diverse responses.