---
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: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/choice-list
  md: >-
    https://shopify.dev/docs/api/customer-account-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/customer-account-ui-extensions/latest/web-components/forms/select).

### Support Targets (24)

### Supported targets

* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Pickup locations**: Let customers choose a store or pickup point from a list of available locations.
* **Preference selection**: Present options with prices and details 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 customers to select multiple options like 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, TEvent>): 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 defines individual selectable options within a choice list, supporting both single selection (radio buttons) and multiple selection (checkboxes) modes.

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

Present options using a choice list component. This example shows a basic choice list for single selection with a pre-selected default.

## Pick from a set of options

![A list of radio button options for selecting a pickup location with the first option pre-selected.](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 location</s-choice
  >
  <s-choice value="location-2">Distillery District location</s-choice>
  <s-choice value="location-3">Yorkville location</s-choice>
</s-choice-list>
```

### Enable multiple selections

Allow customers to select more than one option using checkboxes instead of radio buttons. This example shows a multi-select choice list with descriptive details on each option using the `details` slot.

## html

```html
<s-choice-list label="Notification preferences" name="notifications" multiple>
  <s-choice value="email" selected>
    Email notifications
    <s-text slot="details">
      Receive order updates and shipping confirmations by email.
    </s-text>
  </s-choice>
  <s-choice value="sms">
    SMS notifications
    <s-text slot="details">
      Get text alerts for delivery updates and estimated arrival times.
    </s-text>
  </s-choice>
</s-choice-list>
```

### Show a validation error

Display an error message when a required choice hasn't been made. This example shows a choice list with an `error` message prompting the customer to select an option.

## html

```html
<s-choice-list
  label="Preferred contact method"
  error="Please select a contact method"
>
  <s-choice value="email">Email</s-choice>
  <s-choice value="phone">Phone</s-choice>
  <s-choice value="sms">Text message</s-choice>
</s-choice-list>
```

### Disable a choice list

Prevent interaction while keeping the current selection visible. This example shows a disabled choice list with a pre-selected option.

## html

```html
<s-choice-list label="Account type" name="account-type" disabled>
  <s-choice value="personal" selected>Personal</s-choice>
  <s-choice value="business">Business</s-choice>
  <s-choice value="enterprise">Enterprise</s-choice>
</s-choice-list>
```

***

## Best practices

* **Keep labels concise**: Write short, scannable labels so customers can quickly compare their choices.
* **Add a group label**: Use the `label` property to describe the purpose of the choice list, such as "Shipping speed" or "Contact method."
* **Use select for long lists**: When you have four or more options and screen space is limited, use [select](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/forms/select) to keep the interface compact and scrollable.

***