---
title: ChoiceList
description: >-
  Use choice lists to present a list of choices where buyers can make a single
  selection or multiple selections.
api_version: 2023-10
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2023-10/components/forms/choicelist
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2023-10/components/forms/choicelist.md
---

# Choice​List

Use choice lists to present a list of choices where buyers can make a single selection or multiple selections.

## ChoiceListProps

* name

  string

  required

  An identifier for the field that is unique within the nearest containing `Form` component.

* value

  T

  required

  A `string` or `string[]` indicating the ids of selected choices. When a string is set, choices render as radios. When a string array is set, choices render as checkboxes.

* onChange

  (value: T) => void

  required

  A callback that is run whenever the choice list is changed. This callback is called with a string or array of strings indicating the ids of choices that should now be selected. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), so you must store this value in state and reflect it back in the `value` prop.

Examples

## Preview

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

### Examples

* #### Basic ChoiceList

  ##### JS

  ```js
  import {
    extension,
    ChoiceList,
    Choice,
    BlockStack,
    InlineStack,
  } from '@shopify/ui-extensions/checkout';

  export default extension('purchase.checkout.block.render', (root) => {
    const choiceList = root.createComponent(
      ChoiceList,
      {
        name: 'choice',
        value: 'first',
        onChange: (value) => {
          console.log(`onChange event with value: ${value}`);
        },
      },
      [
        root.createComponent(BlockStack, undefined, [
          root.createComponent(Choice, {id: 'first'}, 'Ship'),
          root.createComponent(Choice, {id: 'second'}, 'Pickup'),
        ]),
      ],
    );

    const multipleChoiceList = root.createComponent(
      ChoiceList,
      {
        name: 'multipleChoice',
        value: ['multipleFirst'],
        onChange: (value) => {
          console.log(`onChange event with value: ${value}`);
        },
      },
      [
        root.createComponent(BlockStack, undefined, [
          root.createComponent(Choice, {id: 'multipleFirst'}, 'Gift message'),
          root.createComponent(Choice, {id: 'multipleSecond'}, 'Gift wrapping'),
        ]),
      ],
    );

    const layout = root.createComponent(InlineStack, undefined, [
      choiceList,
      multipleChoiceList,
    ]);

    root.appendChild(layout);
  });
  ```

  ##### React

  ```tsx
  import {
    reactExtension,
    ChoiceList,
    Choice,
    BlockStack,
    InlineStack,
  } from '@shopify/ui-extensions-react/checkout';

  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    return (
      <InlineStack>
        <ChoiceList
          name="choice"
          value="first"
          onChange={(value) => {
            console.log(
              `onChange event with value: ${value}`,
            );
          }}
        >
          <BlockStack>
            <Choice id="first">Ship</Choice>
            <Choice id="second">Pickup</Choice>
          </BlockStack>
        </ChoiceList>

        <ChoiceList
          name="choiceMultiple"
          value={['multipleFirst']}
          onChange={(value) => {
            console.log(
              `onChange event with value: ${value}`,
            );
          }}
        >
          <BlockStack>
            <Choice id="multipleFirst">
              Gift message
            </Choice>
            <Choice id="multipleSecond">
              Gift wrapping
            </Choice>
          </BlockStack>
        </ChoiceList>
      </InlineStack>
    );
  }
  ```

## Best Practices

* Include a title that either tells customers what to do or explains their available options.

* Label options clearly based on what the option will do.

* Avoid options that contradict each other when you’re allowing for multiple selections.

## Related

[Component - Choice](choice)

[Component - Checkbox](checkbox)