---
title: ChoiceList
description: >-
  The `ChoiceList` 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 offers multiple layout
  variants including list, inline, block, and grid formats to suit different
  space constraints and visual requirements.
api_version: 2025-10
api_name: pos-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-components/forms/choicelist
  md: >-
    https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-components/forms/choicelist.md
---

# Choice​List

The `ChoiceList` 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 offers multiple layout variants including list, inline, block, and grid formats to suit different space constraints and visual requirements.

## Properties

Configure the following properties on the `ChoiceList` component.

* id

  string

  A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.

* multiple

  boolean

  Default: false

  Whether multiple choices can be selected simultaneously.

* values

  string\[]

  An array of the values of the selected options. This is a convenience property for setting the selected state on child choice components.

## Events

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

  (event: CallbackEvent<"s-choice-list">) => void

  Called after editing completes, typically on blur.

* input

  (event: CallbackEvent<"s-choice-list">) => void

  Called when the user makes any changes in the field.

### CallbackEvent

Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.

* bubbles

  Whether the event bubbles up through the DOM tree.

  ```ts
  boolean
  ```

* cancelable

  Whether the event can be canceled.

  ```ts
  boolean
  ```

* composed

  Whether the event will trigger listeners outside of a shadow root.

  ```ts
  boolean
  ```

* currentTarget

  The element that the event listener is attached to.

  ```ts
  HTMLElementTagNameMap[T]
  ```

* detail

  Additional data associated with the event.

  ```ts
  any
  ```

* eventPhase

  The current phase of the event flow.

  ```ts
  number
  ```

* target

  The element that triggered the event.

  ```ts
  HTMLElementTagNameMap[T] | null
  ```

```ts
interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
  /**
   * The element that the event listener is attached to.
   */
  currentTarget: HTMLElementTagNameMap[T];
  /**
   * Whether the event bubbles up through the DOM tree.
   */
  bubbles?: boolean;
  /**
   * Whether the event can be canceled.
   */
  cancelable?: boolean;
  /**
   * Whether the event will trigger listeners outside of a shadow root.
   */
  composed?: boolean;
  /**
   * Additional data associated with the event.
   */
  detail?: any;
  /**
   * The current phase of the event flow.
   */
  eventPhase: number;
  /**
   * The element that triggered the event.
   */
  target: HTMLElementTagNameMap[T] | null;
}
```

## Choice

The `Choice` component creates options that let merchants select one or multiple items from a list of choices.

* disabled

  boolean

  Default: false

  Whether the field is disabled, preventing user interaction. Use when the field is temporarily unavailable due to application state, permissions, or dependencies.

* id

  string

  A unique identifier for the element used for targeting with CSS, JavaScript, or accessibility features.

* selected

  boolean

  Default: false

  Whether the choice control is currently active or selected.

* value

  string

  The unique value associated with this choice option. This value is used to identify the option and gets submitted with forms when selected. Use meaningful values like `"small"`, `"medium"`, or `"large"` rather than display text.

### Examples

* #### Create a choice list for selections

  ##### Description

  Present options using a \`ChoiceList\` component. This example shows a basic choice list for single selection.

  ##### Default

  ```html
  <s-choice-list>
    <s-choice value="s" selected>Small</s-choice>
    <s-choice value="m">Medium</s-choice>
    <s-choice value="l">Large</s-choice>
    <s-choice value="xl">Extra large</s-choice>
  </s-choice-list>
  ```

## Preview

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

## Best practices

* **Choose appropriate selection modes:** Use single selection for mutually exclusive options. Enable `multiple` when merchants can select more than one.
* **Write clear, concise choice labels:** Keep labels short but descriptive enough that merchants understand each option without additional explanation.

## Limitations

`ChoiceList` component types other than `Choice` can't be used as options within the choice list.

## Examples

Learn how to enable multiple selection modes and handle selection events.

### Examples

* #### Enable multiple selection mode

  ##### Description

  Enable multiple selection mode to allow merchants to select multiple options from the list. This example demonstrates using controlled values with the \`multiple\` property, perfect for filtering interfaces or collecting multiple preferences in forms.

  ##### Default

  ```jsx
  <s-choice-list 
    multiple
    values={['small', 'medium']}
    onChange={(event) => console.log('Selected:', event.currentTarget.values)}
  >
    <s-choice value="small">Small</s-choice>
    <s-choice value="medium">Medium</s-choice>
    <s-choice value="large">Large</s-choice>
  </s-choice-list>
  ```

* #### Handle selection events

  ##### Description

  Subscribe to \`onChange\` and \`onInput\` events to respond when merchants select options. This example shows how to handle selection changes and capture user input in real time, enabling dynamic behavior and form validation based on merchant choices.

  ##### Default

  ```jsx
  <s-choice-list
    onChange={(event) => console.log('onChange:', event.currentTarget.values)}
    onInput={(event) => console.log('onInput:', event.currentTarget.values)}
  >
    <s-choice value="option1">Option 1</s-choice>
    <s-choice value="option2" disabled>Option 2 (disabled)</s-choice>
    <s-choice value="option3">Option 3</s-choice>
  </s-choice-list>
  ```

* #### Compose rich choice content

  ##### Description

  Compose rich choice content by nesting other components within \`Choice\` elements. This example demonstrates combining images, text, and layout components to create visually enhanced choice options with descriptions and supporting images.

  ##### Default

  ```jsx
  <s-choice-list>
    {/* Composed choice with image and text */}
    <s-choice value="option1">
      <s-stack gap="small-200" alignItems="center" direction="inline">
        <s-box blockSize="40px" inlineSize="40px">
          <s-image src="https://placehold.co/60x60" inlineSize="fill" objectFit="cover" />
        </s-box>
        <s-box>
          <s-text>Option 1</s-text>
          <s-text type="small" color="subdued">
            Additional details for option 1
          </s-text>
        </s-box>
      </s-stack>
    </s-choice>

    {/* Composed choice with nested text */}
    <s-choice value="option2">
      <s-text type="strong">
        Option 2
        <s-text type="small" color="subdued">
          Additional details for option 2
        </s-text>
      </s-text>
    </s-choice>

    {/* Mix of text and composed elements */}
    <s-choice value="option3" disabled>
      Option 3
      <s-text type="small" color="subdued">
        (disabled)
      </s-text>
      <s-text type="strong">Additional details for option 3</s-text>
    </s-choice>
  </s-choice-list>
  ```