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.

Anchor to PropertiesProperties

Configure the following properties on the choice list component.

Anchor to disabled disabled boolean Default: false required: Whether the field is disabled, preventing any user interaction. When true, the disabled property on any child choices is ignored.
Anchor to name name string required: 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 error error string required: An error message displayed below the checkbox to indicate validation problems. When set, the checkbox is styled with error indicators and the message is announced to screen readers.
Anchor to details details string required: Supplementary text displayed below the checkbox to provide additional context, instructions, or help. Use this to explain what checking the box means or provide guidance to users. This text is announced to screen readers.
Anchor to multiple multiple boolean Default: false required: Whether multiple choices can be selected.
Anchor to label label string required: 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' required: Controls whether the label is visible to all users or only to screen readers.

visible: The label is shown to everyone (default).

exclusive: The label is visually hidden but still announced by screen readers.

Use exclusive when the surrounding context makes the label redundant visually, but screen reader users still need it for clarity.
Anchor to values values string[] required: An array of value attributes for the currently selected options. When provided, this property automatically sets the selected state on child option components that have matching value attributes. Options with values included in this array will be marked as selected, while others will be unselected.

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> | null required: A callback fired when the choice list selection changes.

Learn more about the change event.
Anchor to input input <typeof tagName> | null required: A callback fired when the user inputs data into the choice list.

Learn more about the input event.

CallbackEventListener

A function that handles events from UI components. This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.

(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null

CallbackEvent

An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.

Event & {
  currentTarget: HTMLElementTagNameMap[T];
}

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 disabled disabled boolean Default: false required: Whether the checkbox is disabled, preventing user interaction. Disabled checkboxes appear dimmed and their values aren't submitted with forms.
Anchor to selected selected boolean Default: false required: Whether the option is currently selected. Use this for controlled components where you manage the selection state.
Anchor to value value string required: The value submitted with the form when this checkbox is checked. If not specified, the default value is "on".
Anchor to accessibilityLabel accessibilityLabel string required: A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
Anchor to defaultSelected defaultSelected boolean Default: false required: The initial selected state for uncontrolled components. Use this when you want the option to start selected but don't need to control its state afterward.

Anchor to SlotsSlots

The choice list component supports slots for additional content placement within each choice. Learn more about using slots.

Anchor to children children HTMLElement: The label text or elements that identify this selectable choice to users.

The label is produced by extracting and concatenating the text nodes from the provided content; any markup or element structure is ignored.
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 ExamplesExamples

Anchor to Add a single-select choice listAdd a single-select choice list

Present a group of options for merchants to choose from using radio buttons. This example shows a single-select choice list component with a label, help text, and an onChange handler.

Preview

html

const handleChange = (event) =>

console.log('Values: ', event.currentTarget.values);

</script>

<s-choice-list

label="Company name"

name="Company name"

details="The company name will be displayed on the checkout page."

onChange="handleChange(event)"

<s-choice value="hidden">Hidden</s-choice>

<s-choice value="optional">Optional</s-choice>

<s-choice value="required">Required</s-choice>

</s-choice-list>

Anchor to Pre-select a default optionPre-select a default option

Set a default selection so merchants see a pre-selected option when the form loads. This example shows a single-select choice list with one option already selected.

Preview

html

<s-choice-list label="Product visibility" name="visibility">

<s-choice value="hidden">Hidden</s-choice>

<s-choice value="optional">Optional</s-choice>

<s-choice value="required" selected>Required</s-choice>

</s-choice-list>

Anchor to Enable multiple selections with detailsEnable multiple selections with details

Allow merchants to select more than one option using checkboxes instead of radio buttons. This example shows a multi-select choice list with descriptive details on each option.

Preview

html

<s-choice-list label="Checkout options" name="checkout" multiple>

<s-choice value="shipping" selected>

Use the shipping address as the billing address by default

<s-text slot="details">

Reduces the number of fields required to check out. The billing address

can still be edited.

</s-text>

</s-choice>

<s-choice value="confirmation">

Require a confirmation step

<s-text slot="details">

Customers must review their order details before purchasing.

</s-text>

</s-choice>

</s-choice-list>

Anchor to Show a validation errorShow a validation error

Display an error message when a selection is invalid or a required choice has not been made. This example shows a choice list with a static error message.

Preview

html

<s-choice-list

label="Product visibility"

error="Please select an option"

<s-choice value="hidden">Hidden</s-choice>

<s-choice value="optional">Optional</s-choice>

<s-choice value="required">Required</s-choice>

</s-choice-list>

Anchor to Disable a choice listDisable a choice list

Disable a choice list to prevent interaction while keeping the current selection visible. This example shows a disabled choice list with a pre-selected option.

Preview

html

<s-choice-list label="Account type" name="account-type" disabled>

<s-choice value="basic" selected>Basic</s-choice>

<s-choice value="advanced">Advanced</s-choice>

<s-choice value="enterprise">Enterprise</s-choice>

</s-choice-list>

Anchor to Best practicesBest practices

Choose appropriate selection modes: Use single selection for mutually exclusive options like payment methods or shipping speeds. Enable multiple when merchants can select more than one.
Write clear, specific labels: Use choice labels that describe the outcome, like Email notifications for new orders rather than just Email. Keep labels concise but descriptive enough that merchants understand each option without additional explanation.
Write clear titles: Use titles that pose a clear question or statement, like Which shipping method? or Select notification preferences. Avoid vague titles like Options or Settings.
Add context to complex choices: Use the details slot on individual choices (for example, <s-text slot="details">) to explain implications when needed.
Provide actionable validation: Show specific error messages like Please select at least one notification preference rather than generic Required field.

Anchor to LimitationsLimitations

The component doesn't include search, filtering, or lazy loading. For large option sets (20+ choices), consider using a select dropdown instead.
Rendering 50+ checkboxes or radio buttons can cause noticeable performance issues, especially on mobile devices. Consider pagination, virtualization, or alternative UI patterns for large lists.
The component is either single-selection (radio buttons) or multiple-selection (checkboxes) for all choices. You can't mix both types in the same list.
Component types other than choice can't be used as options within the choice list.

Was this page helpful?