---
title: ChoiceList
description: Present multiple options to users, allowing either single selections with radio buttons or multiple selections with checkboxes.
api_version: 2025-10
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/forms/choicelist
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/polaris-web-components/forms/choicelist.md
---

# Choice​List

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

## Properties

* disabled

  boolean

  Default: false

  Disables the field, disallowing any interaction.

  `disabled` on any child choices is ignored when this is true.

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

* id

  string

  A unique identifier for the element.

* label

  string

  Content to use as the field label.

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

* multiple

  boolean

  Default: false

  Whether multiple choices can be selected.

* name

  string

  An identifier for the field that is unique within the nearest containing form.

* values

  string\[]

  An array of the `value`s of the selected options.

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

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

## Events

* change

  ((event: CallbackEventListener\<typeof tagName>) => void) | null

  A callback that is run whenever the control is changed.

### CallbackEventListener

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, TEvent>): void;
}) | null
```

### CallbackEvent

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

## Choice

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

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

* defaultSelected

  boolean

  Default: false

  Whether the control is active by default.

* disabled

  boolean

  Default: false

  Disables the control, disallowing any interaction.

* error

  boolean

  Default: false

  Set to `true` to associate a choice with the error passed to `ChoiceList`

* id

  string

  A unique identifier for the element.

* selected

  boolean

  Default: false

  Whether the control is active.

* value

  string

  The value used in form data when the control is checked.

## Slots

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

* secondaryContent

  HTMLElement

  Secondary content for a choice.

* selectedContent

  HTMLElement

  Content to display when the option is selected.

  This can be used to provide additional information or options related to the choice.

### Examples

* #### Code

  ##### Default

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

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/choice-list-default.png)