Combobox

Usage

Use a combobox when you need to have a list of options that has search and filtering capabilities. This is a common pattern in web UI and is similar to the native datalist. In contrast to the datalist, a combobox supports making multiple selections and providing a richer UI for each option in the list, including images and styling. Adding free text input that is not part of the predefined list is not supported in the combobox. Do not confuse a combobox element with the datalist or select controls. Datalist elements are good for simple values to search quickly. A select input is useful when you want to use the browser’s native select control because you don’t need more complex searching and filtering capabilities.

See more usage guidelines in our patterns:

Types

Single-selection combobox

This type of combobox is dynamic and generated from an array of data. You supply a template that determines how options are displayed in the list. When an option is selected, its display name is added to the text input box.

Multiple-selection combobox

The multiple-selection combobox is similar to the single-select one, as it is data driven and allows you to determine how options are displayed in the list. After the user selects an option, a pill is created that corresponds to the selected item. The user can then select other options from the drop-down list to add more pills to the pills list.

Asynchronous combobox

The asynchronous combobox allows for lazy loading of the pre-selected options. There is a "loading" spinner and a message that is displayed before the loading is complete.

Anatomy

As a form element, the combobox has a label, which can be vertically or horizontally aligned to it. It also has a condensed mode that occupies less space. It has helper text and an area for error or success messages.
The component itself includes a text input for the user to enter search text and a drop-down list that includes predefined options. You can choose how options are styled.
The multiple-selection version of the combobox also includes pills that are situated before the text input. These pills all feature a delete button and can be styled similar to the options.

Behavior

Filtering the options list

Typing in the input text box filters the drop-down list of predefined options.

Interacting with the current selection

For all combobox types that allow only a single selection, the current selection is pre-filled in the text input box. Once a selection is made, the user cannot change it by using the input text box. Instead, a new option must be selected from the drop-down list. Selections can only be changed, not deleted.
For multiple-selection comboboxes, the current selection is displayed as a list of pills before the input box. New pills can be added from the drop-down list. Pills can be deleted by clicking the "X" icon on each pill. Also, pressing Backspace key in an empty input box will select the last pill in the list.

Opening the drop-down list

To display the predefined options in the drop-down list, the user can either:

• Click the down-caret icon at the end of the input text box.
• Type into the input text box.

Interacting with the options

Options from the drop-down list can be selected using a mouse or by using the keyboard arrow keys and then pressing Enter. Selected options are highlighted in the list and shown in the input text box.