---
title: Choice list
description: >-
  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](/docs/api/checkout-ui-extensions/2026-04/web-components/forms/select).
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list.md
---

# 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](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/select).

### Support Targets (29)

### Supported targets

* purchase.​checkout.​actions.​render-before
* purchase.​checkout.​block.​render
* purchase.​checkout.​cart-line-item.​render-after
* purchase.​checkout.​cart-line-list.​render-after
* purchase.​checkout.​contact.​render-after
* purchase.​checkout.​delivery-address.​render-after
* purchase.​checkout.​delivery-address.​render-before
* purchase.​checkout.​footer.​render-after
* purchase.​checkout.​header.​render-after
* purchase.​checkout.​payment-method-list.​render-after
* purchase.​checkout.​payment-method-list.​render-before
* purchase.​checkout.​pickup-location-list.​render-after
* purchase.​checkout.​pickup-location-list.​render-before
* purchase.​checkout.​pickup-location-option-item.​render-after
* purchase.​checkout.​pickup-point-list.​render-after
* purchase.​checkout.​pickup-point-list.​render-before
* purchase.​checkout.​reductions.​render-after
* purchase.​checkout.​reductions.​render-before
* purchase.​checkout.​shipping-option-item.​details.​render
* purchase.​checkout.​shipping-option-item.​render-after
* purchase.​checkout.​shipping-option-list.​render-after
* purchase.​checkout.​shipping-option-list.​render-before
* purchase.​thank-you.​announcement.​render
* purchase.​thank-you.​block.​render
* purchase.​thank-you.​cart-line-item.​render-after
* purchase.​thank-you.​cart-line-list.​render-after
* purchase.​thank-you.​customer-information.​render-after
* purchase.​thank-you.​footer.​render-after
* purchase.​thank-you.​header.​render-after

## Properties

* **disabled**

  **boolean**

  **Default: false**

  Whether the field is disabled, preventing any user interaction.

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

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

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

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

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

* **multiple**

  **boolean**

  **Default: false**

  Whether multiple choices can be selected.

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

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

Learn more about [registering events](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#event-handling).

* **change**

  **CallbackEventListener\<typeof tagName>**

  A callback fired when the choice list value changes.

  Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/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.

```ts
(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.

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

## Choice

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.

* **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 selected by default.

* **disabled**

  **boolean**

  **Default: false**

  Whether the control is disabled, preventing any user interaction.

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

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

* **selected**

  **boolean**

  **Default: false**

  Whether the control is currently selected.

* **value**

  **string**

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

## Slots

Learn more about [component slots](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#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

## Preview

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

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

* #### List Variant

  ##### Description

  This classic and flexible variant is ideal for \<strong>up to 10 choices\</strong>. It’s the most common and recognizable format for making a selection from a vertical list. \<strong>Best Practices\</strong> \<ul> \<li>\<strong>Keep it simple:\</strong> Keep the initial content for each item as concise as possible so users can quickly scan and compare their choices.\</li> \<li>\<strong>Add extra content strategically:\</strong> Only use the "selected content" slot if the information is \<strong>essential and directly tied\</strong> 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

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

* #### Block Variant

  ##### Description

  This variant is designed for options that require both \<strong>secondary content\</strong> and a clear visual separation. It’s well-suited for \<strong>up to 5 choices\</strong> 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. \<strong>Best Practices\</strong> \<ul> \<li>\<strong>Focus on clarity:\</strong> 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>\<strong>Be intentional with extra content:\</strong> Just like the List variant, only include extra content when it’s \<strong>crucial for the user to make a final decision\</strong> and when its close proximity to the selected block is a benefit.\</li> \</ul>

  ##### Default

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

* #### Inline Variant

  ##### Description

  This compact variant is ideal when \<strong>screen real estate is limited\</strong>. It works best for \<strong>up to 3 to 5 choices\</strong> depending on the typical length of the content. \<strong>Best Practices\</strong> \<ul> \<li>\<strong>Keep content short and simple:\</strong> Due to its horizontal layout, content for each item must be \<strong>succinct, simple, and short\</strong>, especially on mobile.\</li> \<li>\<strong>Avoid extra content:\</strong> 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

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

* #### Grid Variant

  ##### Description

  This variant is best for \<strong>up to 6 choices\</strong>, 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. \<strong>Best Practices\</strong> \<ul> \<li>\<strong>Keep content short and simple:\</strong> The content in each item needs to be \<strong>succinct and simple\</strong> because the horizontal and vertical constraints of the grid can limit the available space.\</li> \<li>\<strong>Avoid extra content:\</strong> 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

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