---
title: Choice
description: >-
  The choice component creates individual selectable options within a choice
  list.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/choice
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/forms/choice.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Choice

The choice component creates individual selectable options within a choice list. The wrapping choice list component dictates whether the choice renders as a radio button or checkbox.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/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/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Radio groups**: Present mutually exclusive options like shipping speed.
* **Checkbox groups**: Let customers select multiple preferences at once.
* **Labeled options**: Provide clear labels and optional secondary text for each choice.
* **Grouped selections**: Organize related options within a single choice list.

***

## Properties

Configure the following properties on the Choice component.

* **id**

  **string**

  **required**

  A unique identifier for the choice.

* **accessibilityLabel**

  **string**

  A label used for buyers using assistive technologies. When set, any `children` supplied to this component will not be announced to screen reader users.

* **details**

  **string | RemoteFragment**

  Additional content to be revealed when selected.

* **disabled**

  **boolean**

  Whether the choice can be changed.

* **primaryContent**

  **string | RemoteFragment**

  The primary content for a choice. Rendered below `<label>`.

* **secondaryContent**

  **string | RemoteFragment**

  The secondary label content for a choice in a `group` ChoiceList. Ignored in `base` [variant](https://shopify.dev/docs/api/checkout-ui-extensions/components/forms/choicelist#choicelistprops-propertydetail-value). Rendered on the opposite side to

* **tertiaryContent**

  **string | RemoteFragment**

  The tertiary label content for a choice in a `group` ChoiceList. Ignored in `base` [variant](https://shopify.dev/docs/api/checkout-ui-extensions/components/forms/choicelist#choicelistprops-propertydetail-value). Rendered below `primaryContent` and `secondaryContent`.

***

## Examples

### Create a selectable option

Use choice to define an individual selectable option inside a choice list. This example shows a single choice rendered as a radio button.

## Create a selectable option

![A selectable option rendered as a radio button within a choice list](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/choice-default-CgBZJC7w.png)

## Create a selectable option

##### React

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

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <InlineStack>
      <ChoiceList
        name="ship"
        value="ship-1"
        onChange={(value) => {
          console.log(
            `onChange event with value: ${value}`,
          );
        }}
      >
        <Choice id="ship-1">Ship</Choice>
      </ChoiceList>

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

##### JS

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

export default extension('customer-account.page.render', (root) => {
  const choiceList = root.createComponent(
    ChoiceList,
    {
      name: 'ship',
      value: 'ship-1',
      onChange: (value) => {
        console.log(`onChange event with value: ${value}`);
      },
    },
    [root.createComponent(Choice, {id: 'ship-1'}, 'Ship')],
  );

  const multipleChoiceList = root.createComponent(
    ChoiceList,
    {
      name: 'gift',
      value: ['gift-1'],
      onChange: (value) => {
        console.log(`onChange event with value: ${value}`);
      },
    },
    [root.createComponent(Choice, {id: 'gift-1'}, 'Gift message')],
  );

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

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

***

## Best practices

* **Include a descriptive title**: Tell customers what to do or explain their available options.
* **Label options clearly**: Base labels on what the option does, not technical values.
* **Avoid contradictory options**: When allowing multiple selections, don't include options that conflict with each other.

***

## Limitations

* Must be used as a child of choice list.

***