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.

ChoiceList

The choice list component presents multiple options for single or multiple selections. Use it when customers need to choose from a defined set of options.

The component supports both single selection (radio button behavior) and multiple selection (checkbox behavior) modes. It includes configurable labels, help text, and validation. For compact dropdown selection with four or more options, use Select.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the ChoiceList component.

Anchor to name
name
string
required

A unique identifier for the field in the closest Form component.

Anchor to onChange
onChange
(value: T) => void
required

A callback fired when the choice list value changes. 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, so you must store this value in state and reflect it back in the value prop.

Anchor to value
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.

Anchor to variant
variant
'base' | 'group'
Default: 'base'

Toggle between base and group look.

Check the best practices to learn more about the variants.

Anchor to ExamplesExamples

Anchor to Pick from a set of optionsPick from a set of options

Use choice list to present a set of options that customers can select from. This example shows a basic single-select choice list with radio buttons.

Pick from a set of options

A choice list with radio button options

Pick from a set of options

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

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

function Extension() {
return (
<InlineStack>
<ChoiceList
name="group-single"
variant="group"
value="ship"
onChange={(value) => {
console.log(
`onChange event with value: ${value}`,
);
}}
>
<Choice
secondaryContent={
<Icon source="truck" />
}
id="ship"
>
Ship
</Choice>
<Choice
secondaryContent={
<Icon source="marker" />
}
id="ship-to-pickup-point"
>
Ship to pickup point
</Choice>
<Choice
secondaryContent={
<Icon source="store" />
}
id="pick-up"
>
Pick up in store
</Choice>
</ChoiceList>
<ChoiceList
name="base-multiple"
value={['remember-me']}
onChange={(value) => {
console.log(
`onChange event with value: ${value}`,
);
}}
>
<BlockStack>
<Choice id="remember-me">
Save this information for next time
</Choice>
<Choice id="email-me">
Email me with news and offers
</Choice>
<Choice id="text-me">
Text me with news and offers
</Choice>
</BlockStack>
</ChoiceList>
</InlineStack>
);
}
import {
extension,
InlineStack,
ChoiceList,
Choice,
BlockStack,
Icon,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const inlineStack = root.createComponent(InlineStack, undefined, [
root.createComponent(
ChoiceList,
{
name: 'group-single',
variant: 'group',
value: 'ship',
onChange: (value) => {
console.log(`onChange event with value: ${value}`);
},
},
[
root.createComponent(
Choice,
{
secondaryContent: root.createComponent(Icon, {source: 'truck'}),
id: 'ship',
},
'Ship',
),
root.createComponent(
Choice,
{
secondaryContent: root.createComponent(Icon, {source: 'marker'}),
id: 'ship-to-pickup-point',
},
'Ship to pickup point',
),
root.createComponent(
Choice,
{
secondaryContent: root.createComponent(Icon, {source: 'store'}),
id: 'pick-up',
},
'Pick up in store',
),
],
),
root.createComponent(
ChoiceList,
{
name: 'base-multiple',
value: ['remember-me'],
onChange: (value) => {
console.log(`onChange event with value: ${value}`);
},
},
[
root.createComponent(BlockStack, undefined, [
root.createComponent(
Choice,
{id: 'remember-me'},
'Save this information for next time',
),
root.createComponent(
Choice,
{id: 'email-me'},
'Email me with news and offers',
),
root.createComponent(
Choice,
{id: 'text-me'},
'Text me with news and offers',
),
]),
],
),
]);

root.appendChild(inlineStack);
});

Anchor to Build a custom survey using the base variantBuild a custom survey using the base variant

The base variant's flexibility allows for the creation of Likert scales using the choice list component. By using layout components, you can easily structure rows and columns for this purpose.

Build a custom survey using the base variant

A Likert scale survey built with the base variant of ChoiceList

Build a custom survey using the base variant

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

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

function Extension() {
return (
<Grid
columns={[
'fill',
'13%',
'13%',
'13%',
'13%',
'13%',
]}
rows="auto"
spacing="none"
border="base"
cornerRadius="base"
overflow="hidden"
>
<View />
<View
padding={['tight', 'extraTight']}
blockAlignment="center"
accessibilityVisibility="hidden"
import {
extension,
Choice,
ChoiceList,
Grid,
TextBlock,
View,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const grid = root.createComponent(
Grid,
{
columns: [
'fill',
'13%',
'13%',
'13%',
'13%',
'13%',
],
rows: 'auto',
spacing: 'none',
border: 'base',
cornerRadius: 'base',
overflow: 'hidden',
},
[
root.createComponent(View, {}, []),
root.createComponent(
View,
{
padding: ['tight', 'extraTight'],
blockAlignment: 'center',

Anchor to Collect additional informationCollect additional information

The choice list's group variant, combined with the details property, allows for the conditional display of information when needed.

Collect additional information

A choice list with conditional detail fields shown for the selected option

Collect additional information

import {
reactExtension,
BlockStack,
Choice,
ChoiceList,
DatePicker,
TextBlock,
TextField,
View,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
return (
<ChoiceList
variant="group"
name="white-glove"
value={['white-glove-1']}
onChange={(value) => {
console.log(
`onChange event with value: ${value}`,
);
}}
>
<Choice
id="white-glove-1"
details={
<>
<BlockStack spacing="base">
<BlockStack spacing="extraTight">
<TextBlock>
Choose a delivery date
</TextBlock>
<View
background="base"
border="base"
cornerRadius="base"
padding="base"
>
<DatePicker selected="" />
</View>
</BlockStack>
<BlockStack spacing="extraTight">
<TextField
label="Additional instructions"
value=""
/>
<TextBlock
appearance="subdued"
size="small"
>
The more detailed the delivery
instructions are, the best we
can make the delivery experience
for you.
</TextBlock>
</BlockStack>
</BlockStack>
</>
}
>
Use white glove delivery service
</Choice>
</ChoiceList>
);
}
import {
extension,
BlockStack,
Choice,
ChoiceList,
DatePicker,
TextBlock,
TextField,
View,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const choiceList = root.createComponent(
ChoiceList,
{
name: 'white-glove',
value: ['white-glove-1'],
onChange: (nextValue) => {
console.log(
`onChange event with value: ${nextValue}`,
);
},
},
[
root.createComponent(
Choice,
{id: 'white-glove-1'},
[
root.createComponent(
BlockStack,
{spacing: 'base'},
[
root.createComponent(
BlockStack,
{spacing: 'extraTight'},
[
root.createComponent(
TextBlock,
{},
'Choose a delivery date',
),
root.createComponent(
View,
{
background: 'base',
border: 'base',
cornerRadius: 'base',
padding: 'base',
},
root.createComponent(
DatePicker,
{selected: ''},
),
),
],
),
root.createComponent(
BlockStack,
{spacing: 'extraTight'},
[
root.createComponent(
TextField,
{
label:
'Additional instructions',
value: '',
},
),
root.createComponent(
TextBlock,
{
appearance: 'subdued',
size: 'small',
},
'The more detailed the delivery instructions are, the best we can make the delivery experience for you.',
),
],
),
],
),
],
),
],
);

root.appendChild(choiceList);
},
);

Anchor to Display a short list of time choicesDisplay a short list of time choices

The choice list component is great for presenting a concise list of options, particularly when showcasing time ranges due to its ample horizontal space. However, if there are more than 5 choices, use the select component instead.

Display a short list of time choices

A choice list displaying time slot options in a compact layout

Display a short list of time choices

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

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

function Extension() {
return (
<ChoiceList
name="time"
value=""
onChange={(value) => {
console.log(
`onChange event with value: ${value}`,
);
}}
>
<BlockStack>
<Choice id="morning">
9:00 AM - 12:00 PM
</Choice>
<Choice id="afternoon">
12:00 PM - 3:00 PM
</Choice>
<Choice id="evening">
3:00 PM - 5:00 PM
</Choice>
</BlockStack>
</ChoiceList>
);
}
import {
extension,
BlockStack,
ChoiceList,
Choice,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const choiceList = root.createComponent(
ChoiceList,
{
name: 'time',
value: '',
onChange: (value) => {
console.log(
`onChange event with value: ${value}`,
);
},
},
[
root.createComponent(BlockStack, {}, [
root.createComponent(
Choice,
{id: 'morning'},
'9:00 AM - 12:00 PM',
),
root.createComponent(
Choice,
{id: 'afternoon'},
'12:00 PM - 3:00 PM',
),
root.createComponent(
Choice,
{id: 'evening'},
'3:00 PM - 5:00 PM',
),
]),
],
);

root.appendChild(choiceList);
},
);

Anchor to Best practicesBest practices

  • Keep labels concise: Write short, scannable labels so customers can quickly compare their choices.
  • Add a group label: Use the label property to describe the purpose of the choice list, such as "Shipping speed" or "Contact method."
  • Use select for long lists: When you have four or more options and screen space is limited, use Select to keep the interface compact and scrollable.

Anchor to LimitationsLimitations

  • Component is either single or multiple selection for all choices.
Was this page helpful?