Upgrade to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use Polaris web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension and avoid being blocked from updating your extension after October 1st 2026.

Choose a version:

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

Anchor to PropertiesProperties

Configure the following properties on the Choice component.

Anchor to id id string required: A unique identifier for the choice.
Anchor to accessibilityLabel 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.
Anchor to details details string | RemoteFragment: Additional content to be revealed when selected.
Anchor to disabled disabled boolean: Whether the choice can be changed.
Anchor to primaryContent primaryContent string | RemoteFragment: The primary content for a choice. Rendered below <label>.
Anchor to secondaryContent secondaryContent string | RemoteFragment: The secondary label content for a choice in a group ChoiceList. Ignored in base variant. Rendered on the opposite side to and primaryContent.
Anchor to tertiaryContent tertiaryContent string | RemoteFragment: The tertiary label content for a choice in a group ChoiceList. Ignored in base variant. Rendered below primaryContent and secondaryContent.

Anchor to ExamplesExamples

Anchor to Create a selectable optionCreate 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

Create a selectable option

import {

reactExtension,

Choice,

ChoiceList,

InlineStack,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

<ChoiceList

name="ship"

value="ship-1"

onChange={(value) => {

console.log(

`onChange event with value: ${value}`,

);

}}

</ChoiceList>

<ChoiceList

name="gift"

value={['gift-1']}

onChange={(value) => {

console.log(

`onChange event with value: ${value}`,

);

}}

Gift message

</Choice>

</ChoiceList>

</InlineStack>

);

}

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

});

React

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

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);
});

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

Must be used as a child of choice list.

Was this page helpful?