Skip to main content

ChoiceList

Use choice lists to present a list of choices where buyers can make a single selection or multiple selections.

Anchor to choicelistpropsChoiceListProps

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 that is run whenever the choice list is changed. 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.

Was this section helpful?

Basic ChoiceList

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

export default reactExtension(
'purchase.checkout.block.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>
);
}

Preview

Anchor to best-practicesBest Practices

Anchor to ContentContent

  • Include a title that either tells customers 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 Types of choicesTypes of choices

A screenshot of two examples for base and group variants

  • The base variant is suitable for straightforward options, such as binary choices like 'yes' or 'no' answers. For simple options that require minimal visual emphasis, the base variant is the recommended choice.
  • The group variant provides increased emphasis on choices through the use of colors, borders, and dividers. If the goal is to draw attention to the available options, the group variant is the ideal choice.

Anchor to Flexibility vs. cohesive experienceFlexibility vs. cohesive experience

  • The base variant offers the flexibility to compose ChoiceLists with custom layouts, allowing for greater design composition possibilities.
  • Given the high level of flexibility offered by the base variant, prioritizing accessibility in the implementation is crucial. It is recommended to avoid using buttons or pressable components within the choices.
  • The group variant adheres to a defined structure and provides excellent adaptability to align with the merchant’s brand. It is the ideal choice when strong cohesion with the merchant’s branding is required. Additionally, depending on the placement of the ChoiceList, Checkout will automatically update its appearance to seamlessly adapt to the surface it is on.

Anchor to Using detailsUsing details

A screenshot of an example of using details

  • The details area should be used only when additional input is required from the customer, specifically related to the choice they have made.
  • If the details area contains lengthy content, consider placing it outside of the ChoiceList to ensure that customers can easily digest the information.

Anchor to Long lists of optionsLong lists of options

  • When faced with a considerable number of options, customers may feel overwhelmed, and it can consume valuable interface space. To address this, consider utilizing components like the Select component to condense options, or employ the Disclosure component to progressively reveal more choices upon customer request. Strategies such as paging, filtering, and searching can be employed to enhance usability.

Anchor to Clickable rowsClickable rows

  • If an entire row needs to be clickable, utilize the group variant, as it is specifically designed to enable clickable rows. In this scenario, the base variant may not provide the desired functionality, as only its content elements can be clicked, not the entire row. Attempting to use buttons or pressables to make an entire row clickable could lead to accessibility issues.
Was this section helpful?

Anchor to examplesExamples

Anchor to example-custom-survey-using-the-base-variantCustom survey using the base variant

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

Anchor to example-collecting-additional-informationCollecting additional information

The ChoiceList’s group variant, combined with the details property, allows for the conditional display of information when needed.

Anchor to example-displaying-a-short-list-of-time-choicesDisplaying a short list of time choices

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

Was this section helpful?

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"

Preview

Anchor to relatedRelated

ComponentChoice
ComponentCheckbox