Skip to main content
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.

Choice

Options inside the ChoiceList component.

The wrapping ChoiceList component will dictate if the choice renders as radio buttons or checkboxes.

Support
Targets (50)

Supported targets

Anchor to ChoicePropsChoiceProps

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

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 Basic ChoiceBasic Choice

Basic Choice

Example

Basic Choice

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

export default reactExtension(
'purchase.checkout.block.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>
);
}
import {
extension,
ChoiceList,
Choice,
InlineStack,
} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.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 title that either tells buyers 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.

Anchor to RelatedRelated

ComponentChoiceList
Was this page helpful?