ChoiceList

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

Anchor to propertiesProperties

Anchor to details details string: Additional text to provide context or guidance for the field. This text is displayed along with the field and its label to offer more information or instructions to the user.

This will also be exposed to screen reader users.
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 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 eventsEvents

Learn more about registering events.

Anchor to change change <typeof tagName> | null
Anchor to input input <typeof tagName> | null

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

Anchor to children children HTMLElement: Content to use as the choice label.

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 secondary-content secondary-content HTMLElement: Additional content to display below the choice label. Can include rich content like TextFields, Buttons, or other interactive components. Event handlers on React components are preserved.

Examples

const handleChange = (event) => {

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

}

return (

<s-choice-list

label="Company name"

name="Company name"

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

onChange={handleChange}

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

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

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

</s-choice-list>

)

Preview

Examples

Code

jsx

const handleChange = (event) => {
  console.log('Values: ', event.currentTarget.values)
}

return (
  <s-choice-list
    label="Company name"
    name="Company name"
    details="The company name will be displayed on the checkout page."
    onChange={handleChange}
  >
    <s-choice value="hidden">Hidden</s-choice>
    <s-choice value="optional">Optional</s-choice>
    <s-choice value="required">Required</s-choice>
  </s-choice-list>
)

html

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

Basic usage

Description

Demonstrates a basic ChoiceList with single selection, showing how to create a group of radio button choices.

jsx

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

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>

Multiple selections

Description

Illustrates a ChoiceList with multiple selection enabled, allowing users to choose multiple options with additional descriptive details for each choice.

jsx

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

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>

With error state

Description

Shows how to display an error message in a ChoiceList when an invalid selection is made or a validation constraint is not met.

jsx

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

html

<s-choice-list
  label="Product visibility"
  name="visibility"
  error="Product visibility cannot be hidden at this time"
>
  <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>

Multiple choices with details

Description

Showcases a multiple-selection ChoiceList with each option including detailed information.

jsx

<s-choice-list
  label="Available shipping methods"
  name="shipping-methods"
  multiple
>
  <s-choice value="standard" selected>
    Standard shipping
    <s-text slot="details">5-7 business days delivery</s-text>
  </s-choice>
  <s-choice value="express" selected>
    Express shipping
    <s-text slot="details">2-3 business days delivery</s-text>
  </s-choice>
  <s-choice value="overnight">
    Overnight shipping
    <s-text slot="details">Next business day delivery</s-text>
  </s-choice>
</s-choice-list>

html

<s-choice-list
  label="Available shipping methods"
  name="shipping-methods"
  multiple
>
  <s-choice value="standard" selected>
    Standard shipping
    <s-text slot="details">5-7 business days delivery</s-text>
  </s-choice>
  <s-choice value="express" selected>
    Express shipping
    <s-text slot="details">2-3 business days delivery</s-text>
  </s-choice>
  <s-choice value="overnight">
    Overnight shipping
    <s-text slot="details">Next business day delivery</s-text>
  </s-choice>
</s-choice-list>

Choice list validation

Description

Interactive example showing required choice validation with dynamic error messages.

jsx

const [error, setError] = useState('Please select at least one option');

return (
  <s-section>
    <s-stack gap="base" justifyContent="start">
      <s-choice-list
        label="Product visibility"
        name="visibility"
        error={error}
        onChange={(e) => {
          setError(e.currentTarget.values.length > 0 ? '' : 'Please select at least one 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>
    </s-stack>
  </s-section>
)

Anchor to best-practicesBest practices

Include a title that tells merchants what to do or explains the available options
Label options clearly based on what the option will do
Avoid mutually exclusive options when allowing multiple selection

Anchor to content-guidelinesContent guidelines

Write titles and choices in sentence case
End titles with a colon if they introduce the list
Start each choice with a capital letter
Don't use commas or semicolons at the end of lines

Was this page helpful?

ChoiceList

Anchor to propertiesProperties

Anchor to eventsEvents

CallbackEventListener

CallbackEvent

Anchor to choiceChoice

Anchor to slotsSlots

Preview

Examples

Code

jsx

html

Basic usage

Description

jsx

html

Multiple selections

Description

jsx

html

With error state

Description

jsx

html

Multiple choices with details

Description

jsx

html

Choice list validation

Description

jsx

Anchor to best-practicesBest practices

Anchor to content-guidelinesContent guidelines