---
title: ChoiceList
description: Presents multiple options for single or multiple selections. Use when merchants need to choose from a defined set of options in forms or filtering interfaces.
api_version: 2025-10
api_name: pos-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-componentsforms/choicelist
  md: https://shopify.dev/docs/api/pos-ui-extensions/latest/polaris-web-componentsforms/choicelist.md
---

# Choice​List

Presents multiple options for single or multiple selections. Use when merchants need to choose from a defined set of options in forms or filtering interfaces.

## Properties

* id

  string

  A unique identifier for the element.

* multiple

  boolean

  Default: false

  Whether multiple choices can be selected.

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

## Events

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

* change

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

  Callback when the user changes a choice. Fires simultaneously with onInput.

* input

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

  Callback when the user changes a choice. Fires simultaneously with onChange.

### CallbackEvent

* bubbles

  ```ts
  boolean
  ```

* cancelable

  ```ts
  boolean
  ```

* composed

  ```ts
  boolean
  ```

* currentTarget

  ```ts
  HTMLElementTagNameMap[T]
  ```

* detail

  ```ts
  any
  ```

* eventPhase

  ```ts
  number
  ```

* target

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

```ts
interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
  currentTarget: HTMLElementTagNameMap[T];
  bubbles?: boolean;
  cancelable?: boolean;
  composed?: boolean;
  detail?: any;
  eventPhase: number;
  target: HTMLElementTagNameMap[T] | null;
}
```

## Choice

Creates options that let merchants select one or multiple items from a list of choices.

* disabled

  boolean

  Default: false

  Disables the control, disallowing any interaction.

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

### Examples

* #### Code

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

## Examples

ChoiceList usage patterns

### Examples

* #### Multiple selection

  ##### Description

  Enable multiple selection mode with controlled values

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

* #### Event handling

  ##### Description

  Handle onChange and onInput events.

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