Skip to main content

Choice list

The choice list component presents multiple options for single or multiple selections. Use it when merchants need to choose from a defined set of options, such as filtering results or collecting preferences.

The component supports both single selection (radio button behavior) and multiple selection (checkbox behavior) modes. It includes configurable labels, help text, and validation. For compact dropdown selection with four or more options, use select.

Support
Targets (24)

Supported targets

  • customer-account.footer.render-after
  • customer-account.order-index.announcement.render
  • customer-account.order-index.block.render
  • customer-account.order-status.announcement.render
  • customer-account.order-status.block.render
  • customer-account.order-status.cart-line-item.render-after
  • customer-account.order-status.cart-line-list.render-after
  • customer-account.order-status.customer-information.render-after
  • customer-account.order-status.fulfillment-details.render-after
  • customer-account.order-status.payment-details.render-after
  • customer-account.order-status.return-details.render-after
  • customer-account.order-status.unfulfilled-items.render-after
  • customer-account.order.action.menu-item.render
  • customer-account.order.action.render
  • customer-account.order.page.render
  • customer-account.page.render
  • customer-account.profile.addresses.render-after
  • customer-account.profile.announcement.render
  • customer-account.profile.block.render
  • customer-account.profile.company-details.render-after
  • customer-account.profile.company-location-addresses.render-after
  • customer-account.profile.company-location-payment.render-after
  • customer-account.profile.company-location-staff.render-after
  • customer-account.profile.payment.render-after

Anchor to propertiesProperties

Anchor to disabled
disabled
boolean
Default: false

Disables the field, disallowing any interaction.

disabled on any child choices is ignored when this is true.

Anchor to error
error
string

Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.

Anchor to id
id
string

A unique identifier for the element.

Anchor to label
label
string

Content to use as the field label.

Anchor to labelAccessibilityVisibility
labelAccessibilityVisibility
'visible' | 'exclusive'
Default: 'visible'

Changes the visibility of the component's label.

  • visible: the label is visible to all users.
  • exclusive: the label is visually hidden but remains in the accessibility tree.
Anchor to multiple
multiple
boolean
Default: false

Whether multiple choices can be selected.

Anchor to name
name
string

An identifier for the field that is unique within the nearest containing form.

Anchor to values
values
string[]

An array of the values of the selected options.

This is a convenience prop for setting the selected prop on child options.

Anchor to variant
variant
'auto' | 'list' | 'inline' | 'block' | 'grid'
Default: 'auto'

The variant of the choice grid.

  • auto: The variant is determined by the context.
  • list: The choices are displayed in a list.
  • inline: The choices are displayed on the inline axis.
  • block: The choices are displayed on the block axis.
  • grid: The choices are displayed in a grid.

Anchor to eventsEvents

Learn more about registering events.

Anchor to change
change
<typeof tagName>

A callback that is run whenever the control is changed.

Anchor to choiceChoice

The choice component creates individual selectable options within a choice list. Use choice to define each option that merchants can select, supporting both single selection (radio buttons) and multiple selection (checkboxes) modes.

Choice components support labels, help text, and custom content through slots, providing flexible option presentation within choice lists.

Anchor to accessibilityLabel
accessibilityLabel
string

A label used for users using assistive technologies like screen readers. When set, any children or label supplied will not be announced. This can also be used to display a control without a visual label, while still providing context to users using screen readers.

Anchor to defaultSelected
defaultSelected
boolean
Default: false

Whether the control is active by default.

Anchor to disabled
disabled
boolean
Default: false

Disables the control, disallowing any interaction.

Anchor to error
error
boolean
Default: false

Set to true to associate a choice with the error passed to ChoiceList

Anchor to id
id
string

A unique identifier for the element.

Anchor to selected
selected
boolean
Default: false

Whether the control is active.

Anchor to value
value
string

The value used in form data when the control is checked.

Anchor to slotsSlots

Learn more about component slots.

Anchor to details
details
HTMLElement

Additional text to provide context or guidance for the input.

This text is displayed along with the input and its label to offer more information or instructions to the user.

Anchor to secondaryContent
secondaryContent
HTMLElement

Secondary content for a choice.

Anchor to selectedContent
selectedContent
HTMLElement

Content to display when the option is selected.

This can be used to provide additional information or options related to the choice.

Examples
<s-choice-list>
<s-choice defaultSelected value="location-1"
>Yonge-Dundas Square locations</s-choice
>
<s-choice value="location-2">Distillery District location</s-choice>
<s-choice value="location-3">Yorkville location</s-choice>
</s-choice-list>

Preview

Was this page helpful?