Listbox

The Listbox component is a list component that implements part of the Aria 1.2 Listbox specs. It presents a list of options and allows users to select one or more of them. If you need more structure than the standard component offers, use composition to customize the presentation of these lists by using headers or custom elements.

Examples

Basic implementation of a control element used to let merchants select options

Drag to resize example

Props

accessibilityLabel
string
Visually hidden text for screen readers
childrenRequired
ReactNode
Inner content of the listbox
enableKeyboardControl
boolean
Explicitly enable keyboard control
onSelect
(value: string) => void
Callback when an option is selected

Accessibility

Structure

The Listbox component is based on the Aria 1.2 Listbox pattern.

It is important to not present interactive elements inside of list box options as they can interfere with navigation for assistive technology users.

  • Use labels

  • Use interactive elements inside the list

Keyboard support

  • Access the list of options with the up and down arrow keys
  • Select an option that has focus with the enter/return key

Best practices

Listboxes should:

  • Be clearly labeled so it’s noticeable to the merchant what type of options will be available
  • Limit the number of options displayed at once
  • Indicate a loading state to the merchant while option data is being populated

Content guidelines

Option lists

Each item in a Listbox should be clear and descriptive.

  • Traffic referrer source

  • Source