Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

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?