Choose a version:

ChoiceList

Present multiple options to users, allowing either single selections with radio buttons or multiple selections with checkboxes.

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.

Was this section helpful?

Anchor to eventsEvents

Learn more about registering events.

Anchor to change change <typeof tagName>: A callback that is run whenever the control is changed.

Was this section helpful?

Anchor to choiceChoice

Create options that let users select one or multiple items from a list of choices.

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.

Was this section helpful?

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.

Was this section helpful?

Code

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

Examples

Code

Default

<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

The ChoiceList component offers different variants to suit various use cases. Choose the right variant based on the number of choices, the complexity of the content, and the available screen space. Below are some best practices for each variant.

Anchor to example-list-variantList Variant

This classic and flexible variant is ideal for up to 10 choices. It’s the most common and recognizable format for making a selection from a vertical list.

Best Practices

Keep it simple: Keep the initial content for each item as concise as possible so users can quickly scan and compare their choices.
Add extra content strategically: Only use the "selected content" slot if the information is essential and directly tied to the selected item. For example, a map that shows the location of a chosen address is an effective use case. If the content doesn’t need to be in close proximity to the selected item, place it elsewhere on the page to reduce visual clutter.

Anchor to example-block-variantBlock Variant

This variant is designed for options that require both secondary content and a clear visual separation. It’s well-suited for up to 5 choices where each item is complex and needs its own defined space. Due to its "chunky" footprint, using more than 5 can take up too much vertical space.

Best Practices

Focus on clarity: Use this variant to help users compare options with more complexity than a simple list, such as an item with a title, a description, and a price.
Be intentional with extra content: Just like the List variant, only include extra content when it’s crucial for the user to make a final decision and when its close proximity to the selected block is a benefit.

Anchor to example-inline-variantInline Variant

This compact variant is ideal when screen real estate is limited. It works best for up to 3 to 5 choices depending on the typical length of the content.

Best Practices

Keep content short and simple: Due to its horizontal layout, content for each item must be succinct, simple, and short, especially on mobile.
Avoid extra content: This variant does not support extra content upon selection, so it’s best for a scenario where the user's decision doesn’t require additional information.

Anchor to example-grid-variantGrid Variant

This variant is best for up to 6 choices, arranged in a grid-like layout. It’s great for scenarios where choices have significant visual differences and need to be arranged for easy comparison.

Best Practices

Keep content short and simple: The content in each item needs to be succinct and simple because the horizontal and vertical constraints of the grid can limit the available space.
Avoid extra content: This variant does not support extra content upon selection, so it’s best for a scenario where the user's decision doesn’t require additional information.

Was this section helpful?

List Variant

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

Examples

List Variant
Description
This classic and flexible variant is ideal for up to 10 choices. It’s the most common and recognizable format for making a selection from a vertical list. Best Practices <ul> <li>Keep it simple: Keep the initial content for each item as concise as possible so users can quickly scan and compare their choices.</li> <li>Add extra content strategically: Only use the "selected content" slot if the information is essential and directly tied to the selected item. For example, a map that shows the location of a chosen address is an effective use case. If the content doesn’t need to be in close proximity to the selected item, place it elsewhere on the page to reduce visual clutter.</li> </ul>
Default
```
<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>
```

Block Variant

Description

This variant is designed for options that require both secondary content and a clear visual separation. It’s well-suited for up to 5 choices where each item is complex and needs its own defined space. Due to its "chunky" footprint, using more than 5 can take up too much vertical space. Best Practices <ul> <li>Focus on clarity: Use this variant to help users compare options with more complexity than a simple list, such as an item with a title, a description, and a price.</li> <li>Be intentional with extra content: Just like the List variant, only include extra content when it’s crucial for the user to make a final decision and when its close proximity to the selected block is a benefit.</li> </ul>

Default

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

Inline Variant
Description
This compact variant is ideal when screen real estate is limited. It works best for up to 3 to 5 choices depending on the typical length of the content. Best Practices <ul> <li>Keep content short and simple: Due to its horizontal layout, content for each item must be succinct, simple, and short, especially on mobile.</li> <li>Avoid extra content: This variant does not support extra content upon selection, so it’s best for a scenario where the user's decision doesn’t require additional information.</li> </ul>
Default
```
<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>
```
Grid Variant
Description
This variant is best for up to 6 choices, arranged in a grid-like layout. It’s great for scenarios where choices have significant visual differences and need to be arranged for easy comparison. Best Practices <ul> <li>Keep content short and simple: The content in each item needs to be succinct and simple because the horizontal and vertical constraints of the grid can limit the available space.</li> <li>Avoid extra content: This variant does not support extra content upon selection, so it’s best for a scenario where the user's decision doesn’t require additional information.</li> </ul>
Default
```
<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>
```

ChoiceList

Anchor to propertiesProperties

Anchor to eventsEvents

CallbackEventListener

CallbackEvent

Anchor to choiceChoice

Anchor to slotsSlots

Code

Examples

Code

Default

Preview

Anchor to examplesExamples

List Variant

Examples

List Variant

Description

Default

Block Variant

Description

Default

Inline Variant

Description

Default

Grid Variant

Description

Default

Preview