Skip to main content

ChoiceList

The ChoiceList 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 offers multiple layout variants including list, inline, block, and grid formats to suit different space constraints and visual requirements.

Support
Targets (10)

Supported targets

Use cases

  • Option selection: Create fields where users select one or multiple options from a list.
  • Filtering: Implement filtering where users select categories or attributes to refine content.
  • Settings: Provide configuration options where users choose preferences.
  • Multi-select: Enable scenarios like choosing multiple product variants or categories.

Anchor to examplesExamples

Anchor to example-create-a-choice-list-for-selectionsCreate a choice list for selections

Present options using a ChoiceList component. This example shows a basic choice list for single selection.

Create a choice list for selections

Create a choice list for selections

<s-choice-list>
<s-choice value="s" selected>Small</s-choice>
<s-choice value="m">Medium</s-choice>
<s-choice value="l">Large</s-choice>
<s-choice value="xl">Extra large</s-choice>
</s-choice-list>

Anchor to example-enable-multiple-selection-modeEnable multiple selection mode

Enable multiple selection mode to allow merchants to select multiple options from the list. This example demonstrates using controlled values with the multiple property, perfect for filtering interfaces or collecting multiple preferences in forms.

Enable multiple selection mode

<s-choice-list
multiple
values={['small', 'medium']}
onChange={(event) => console.log('Selected:', event.currentTarget.values)}
>
<s-choice value="small">Small</s-choice>
<s-choice value="medium">Medium</s-choice>
<s-choice value="large">Large</s-choice>
</s-choice-list>

Anchor to example-handle-selection-eventsHandle selection events

Subscribe to onChange and onInput events to respond when merchants select options. This example shows how to handle selection changes and capture user input in real time, enabling dynamic behavior and form validation based on merchant choices.

Handle selection events

<s-choice-list
onChange={(event) => console.log('onChange:', event.currentTarget.values)}
onInput={(event) => console.log('onInput:', event.currentTarget.values)}
>
<s-choice value="option1">Option 1</s-choice>
<s-choice value="option2" disabled>Option 2 (disabled)</s-choice>
<s-choice value="option3">Option 3</s-choice>
</s-choice-list>

Anchor to example-compose-rich-choice-contentCompose rich choice content

Compose rich choice content by nesting other components within Choice elements. This example demonstrates combining images, text, and layout components to create visually enhanced choice options with descriptions and supporting images.

Compose rich choice content

<s-choice-list>
{/* Composed choice with image and text */}
<s-choice value="option1">
<s-stack gap="small-200" alignItems="center" direction="inline">
<s-box blockSize="40px" inlineSize="40px">
<s-image src="https://placehold.co/60x60" inlineSize="fill" objectFit="cover" />
</s-box>
<s-box>
<s-text>Option 1</s-text>
<s-text type="small" color="subdued">
Additional details for option 1
</s-text>
</s-box>
</s-stack>
</s-choice>

{/* Composed choice with nested text */}
<s-choice value="option2">
<s-text type="strong">
Option 2
<s-text type="small" color="subdued">
Additional details for option 2
</s-text>
</s-text>
</s-choice>

{/* Mix of text and composed elements */}
<s-choice value="option3" disabled>
Option 3
<s-text type="small" color="subdued">
(disabled)
</s-text>
<s-text type="strong">Additional details for option 3</s-text>
</s-choice>
</s-choice-list>

Anchor to propertiesProperties

Configure the following properties on the ChoiceList component.

Anchor to id
id
string

A unique identifier for the element.

Anchor to multiple
multiple
boolean
Default: false

Whether multiple choices can be selected.

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 eventsEvents

The ChoiceList component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to change
change
(event: <"s-choice-list">) => void

Callback when the user changes a choice. Fires simultaneously with onInput.

Anchor to input
input
(event: <"s-choice-list">) => void

Callback when the user changes a choice. Fires simultaneously with onChange.

Anchor to choiceChoice

The Choice component creates options that let merchants select one or multiple items from a list of choices.

Anchor to disabled
disabled
boolean
Default: false

Disables the control, disallowing any interaction.

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 best-practicesBest practices

  • Choose appropriate selection modes: Use single selection for mutually exclusive options. Enable multiple when merchants can select more than one.
  • Write clear, concise choice labels: Keep labels short but descriptive enough that merchants understand each option without additional explanation.

Anchor to limitationsLimitations

ChoiceList component types other than Choice can't be used as options within the choice list.

Was this page helpful?