Option list

The option list component lets you create a list of grouped items that merchants can pick from. This can include single selection or multiple selection of options. Option list usually appears in a popover, and sometimes in a modal or a sidebar. Option lists are styled differently than choice lists and should not be used within a form, but as a standalone menu.

Examples

Use for a group of similar selectable items when only one should be selectable at once.

Drag to resize example

Props

allowMultiple
boolean
Allow more than one option to be selected
id
string
A unique identifier for the option list
optionRole
string
Defines a specific role attribute for each option in the list
options
OptionDescriptor[]
Collection of options to be listed
role
"listbox" | "combobox" | string
Defines a specific role attribute for the list itself
sections
SectionDescriptor[]
Sections containing a header and related options
selectedRequired
string[]
The selected options
title
string
List title
verticalAlign
"top" | "center" | "bottom"
Vertically align child content to the center, top, or bottom.
onChangeRequired
(selected: string[]) => void
Callback when selection is changed

Accessibility

Items in an option list are organized as list items (<li>) in an unordered list (<ul>) and are conveyed as a group of related elements to assistive technology users.

Controls in simple option lists are buttons, and controls in multiple option lists are checkboxes.

If you customize the option list, you can provide ARIA roles that fit the context. These roles must be valid according to the W3C ARIA specification to be conveyed correctly to screen reader users.

  • The role prop adds an ARIA role to the option list wrapper
  • The optionRole prop adds an ARIA role to the option list items

Best practices

The option list component should:

  • Be placed on its own inside a container. Usually the container behaves like a menu, as it does with popover. Don’t place other components within the same container.
  • Not be used when a select component will do.

Content guidelines

Option lists

Each item in an option list should be clear and descriptive.

  • Traffic referrer source

  • Source

Edit source on GitHub