Choose a version:

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 (29)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the choice list component.

Anchor to disabled disabled boolean Default: false: Whether the field is disabled, preventing any user interaction.

disabled on any child choices is ignored when this is true.
Anchor to error error string: An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators and the message is announced to screen readers.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to label label string: The text displayed as the field label, which identifies the purpose of the field to users. This label is associated with the field for accessibility and helps users understand what information to provide.
Anchor to labelAccessibilityVisibility labelAccessibilityVisibility 'visible' | 'exclusive' Default: 'visible': Controls whether the label is visible to all users or only to screen readers.

visible: The label is shown to everyone.

exclusive: The label is visually hidden but still announced by screen readers.
Anchor to multiple multiple boolean Default: false: Whether multiple choices can be selected.
Anchor to name name string: The name attribute for the field, used to identify the field's value when the form is submitted. Must be unique within the nearest containing form.
Anchor to values values string[]: An array of value attributes for the currently selected options.

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

Form data captures the selected value strings only. Complex nested content inside choices is for display purposes and isn't included in form submissions.
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.

The selected content slot is supported only in the default (stacked) variant. inline and grid ignore it.

Anchor to EventsEvents

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

Anchor to change change <typeof tagName>: A callback fired when the choice list value changes.

Learn more about the change event.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}

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 selected by default.
Anchor to disabled disabled boolean Default: false: Whether the control is disabled, preventing any user interaction.
Anchor to error error boolean Default: false: Whether this choice is associated with the error state of the parent choice list. When true, the choice is visually marked as having an error.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to selected selected boolean Default: false: Whether the control is currently selected.
Anchor to value value string: The value used in form data when the control is checked.

Anchor to SlotsSlots

The choice component supports slots for additional content placement within the component. Learn more about using 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.

Anchor to ExamplesExamples

Anchor to Pick from a set of optionsPick from a set of options

Create a single-select list with a pre-selected default. This example shows an s-choice-list with three pickup locations, one pre-selected using defaultSelected.

Pick from a set of options

A rendered example of the choice-list component

html

<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>

Anchor to Display a vertical listDisplay a vertical list

Display a vertical list of options for up to 10 choices. This example displays the default list variant with concise labels for each option.

html

<s-choice-list>

<s-choice defaultSelected value="location-1">Yonge-Dundas Square</s-choice>

<s-choice value="location-2">Distillery District</s-choice>

<s-choice value="location-3">Yorkville</s-choice>

</s-choice-list>

Anchor to Present options with detailsPresent options with details

Present detailed options with descriptions and prices in separate blocks. This example uses the block variant with titles, descriptions, and prices for up to five choices.

html

<s-choice-list variant="block">

<s-choice defaultSelected value="yonge-dundas">

<s-stack

direction="inline"

justifyContent="space-between"

alignItems="start"

<s-stack gap="none">

<s-text>Yonge-Dundas Square</s-text>

<s-text slot="secondary-content" type="small" color="subdued"

>1 Dundas St E, Toronto ON</s-text

</s-stack>

<s-text color="subdued">1.2 km</s-text>

</s-stack>

</s-choice>

<s-choice value="distillery">

<s-stack

direction="inline"

justifyContent="space-between"

alignItems="start"

<s-stack gap="none">

<s-text>Distillery District</s-text>

<s-text slot="secondary-content" type="small" color="subdued"

>55 Mill St, Toronto ON</s-text

</s-stack>

<s-text color="subdued">4 km</s-text>

</s-stack>

</s-choice>

<s-choice value="yorkville">

<s-stack

direction="inline"

justifyContent="space-between"

alignItems="start"

<s-stack gap="none">

<s-text>Yorkville</s-text>

<s-text slot="secondary-content" type="small" color="subdued"

>55 Avenue Rd, Toronto ON</s-text

</s-stack>

<s-text color="subdued">6 km</s-text>

</s-stack>

</s-choice>

</s-choice-list>

Anchor to Arrange options horizontallyArrange options horizontally

Arrange options horizontally for compact layouts with limited screen space. This example configures the inline variant with short labels for up to 3-5 choices.

html

<s-choice-list variant="inline">

<s-choice defaultSelected value="3.50">$3.50</s-choice>

<s-choice value="4.50">$4.50</s-choice>

<s-choice value="5.50">$5.50</s-choice>

<s-choice value="other">Other</s-choice>

</s-choice-list>

Anchor to Display options in a gridDisplay options in a grid

Lay out options in a grid for visual comparison of up to six choices. This example shows the grid variant with short labels arranged in rows and columns.

html

<s-choice-list variant="grid">

<s-choice defaultSelected value="standard">Standard</s-choice>

<s-choice value="deluxe">Deluxe</s-choice>

<s-choice value="personalized">Personalized</s-choice>

</s-choice-list>

Anchor to Best practicesBest practices

Choose the right variant: Use list for up to 10 options, block for complex items with secondary content, inline for 3-5 short labels, and grid for visual comparison of up to 6 items.
Keep labels concise: Write short, scannable labels so buyers can quickly compare their choices.
Use selected content sparingly: Only show extra content in the "selected content" slot when it's essential for the buyer's decision, such as a map for a selected pickup location.
Use select for long lists: When you have more than 10 options, use select to keep the interface compact.
Add a group label: Use the label property to describe the purpose of the choice list, such as "Shipping speed" or "Contact method."

Was this page helpful?