---
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.
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/latest/web-components/forms/select).

### Support Targets (29)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

#### Use cases

* **Pickup locations:** Let buyers choose a store or pickup point from a list of available locations.
* **Shipping methods:** Present shipping options with prices and delivery estimates in a block layout.
* **Size or variant selection:** Display product variants in a compact inline or grid layout for quick comparison.
* **Multi-select preferences:** Allow buyers to select multiple options like gift add-ons or notification preferences.

***

## Properties

Configure the following properties on the choice list component.

* **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 `value` attributes for the currently selected options.

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

  Form data captures the selected value strings only. Complex nested content inside choices is for display purposes and isn't included in form submissions.

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

  The selected content slot is supported only in the default (stacked) variant. `inline` and `grid` ignore it.

### Events

The choice list component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

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

The choice component supports slots for additional content placement within the component. Learn more about [using slots](https://shopify.dev/docs/api/polaris/using-polaris-web-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

### Pick from a set of options

Create a single-select list with a pre-selected default. This example shows an `s-choice-list` with three pickup locations, one pre-selected using `defaultSelected`.

## Pick from a set of options

![A rendered example of the choice-list component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/choice-list-default-D6RTGm1A.png)

## html

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

### Display a vertical list

Display a vertical list of options for up to 10 choices. This example displays the default list variant with concise labels for each option.

## html

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

### Present options with details

Present detailed options with descriptions and prices in separate blocks. This example uses the block variant with titles, descriptions, and prices for up to five choices.

## html

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

### Arrange options horizontally

Arrange options horizontally for compact layouts with limited screen space. This example configures the inline variant with short labels for up to 3-5 choices.

## html

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

### Display options in a grid

Lay out options in a grid for visual comparison of up to six choices. This example shows the grid variant with short labels arranged in rows and columns.

## html

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

***

## Best practices

* **Choose the right variant:** Use list for up to 10 options, block for complex items with secondary content, inline for 3-5 short labels, and grid for visual comparison of up to 6 items.
* **Keep labels concise:** Write short, scannable labels so buyers can quickly compare their choices.
* **Use selected content sparingly:** Only show extra content in the "selected content" slot when it's essential for the buyer's decision, such as a map for a selected pickup location.
* **Use select for long lists:** When you have more than 10 options, use [select](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/select) to keep the interface compact.
* **Add a group label:** Use the `label` property to describe the purpose of the choice list, such as "Shipping speed" or "Contact method."

***