List box
A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements.
Props
No props found for this component, run `yarn gen:docs` to generate component meta first.
Slots
No slots found for this component, run `yarn gen:docs` to generate component meta first.
Anatomy
![A diagram of the Listbox component showing the smaller primitive components it can be composed of.]
A listbox can be composed of:
- Options: The individual options inside the Listbox that merchants can select or deselect.
- Dividers: Placed between items and are useful in complex lists when there’s a lot of information for the merchant to parse.
- Section headers: Used at the begining of a section when it’s necessary to call out the content being displayed. In most cases, the surrounding context should be enough for the merchant to understand the information in the list.
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.
Patterns that use Listbox
Location picker
Related components
- For a text field and popover container, use the combobox component
- Autocomplete can be used as a convenience wrapper in lieu of Combobox and Listbox.
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.
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