Combobox

The Combobox component implements part of the Aria 1.2 combobox specs on a TextField and a popover containing a Listbox. Like Autocomplete, Combobox allows merchants to quickly search through and select from large collections of options.

Examples

Use to help merchants complete text input quickly from a list of options.

Drag to resize example

Props

activatorRequired
ReactElement
allowMultiple
boolean
children
ReactElement | null
preferredPosition
"above" | "below" | "mostSpace"
onScrolledToBottom
() => void

Accessibility

Structure

The Combobox component is based on the ARIA 1.2 combobox pattern. It is a combination of a single-line TextField and a Popover. The current implementation expects a Listbox component to be used.

The Combobox popover displays below the text field or other control by default so it is easy for merchants to discover and use. However, you can change the position with the preferredPosition prop.

Combobox features can be challenging for merchants with visual, motor, and cognitive disabilities. Even when they’re built using best practices, these features can be difficult to use with some assistive technologies. Merchants should always be able to search, enter data, or perform other activities without relying on the combobox.

Do

  • Use combobox as progressive enhancement to make the interface easier to use for most merchants.

Don’t

  • Require that merchants make a selection from the combobox to complete a task.

Keyboard support

  • Give the combobox's text input keyboard focus with the tab key (or shift + tab when tabbing backwards)

Best practices

The Combobox component should:

  • Be clearly labeled so it’s noticeable to the merchant what type of options will be available
  • Not be used within a popover
  • Indicate a loading state to the merchant while option data is being populated

Content guidelines

The input field for Combobox should follow the content guidelines for text fields.