Choose a version:

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: An identifier for the field that is unique within the nearest containing Form component.
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 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.

Examples

import {

extension,

ChoiceList,

Choice,

BlockStack,

InlineStack,

} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {

const choiceList = root.createComponent(

ChoiceList,

{

name: 'choice',

value: 'first',

onChange: (value) => {

console.log(`onChange event with value: ${value}`);

},

[

root.createComponent(BlockStack, undefined, [

root.createComponent(Choice, {id: 'first'}, 'Ship'),

root.createComponent(Choice, {id: 'second'}, 'Pickup'),

]),

],

);

const multipleChoiceList = root.createComponent(

ChoiceList,

{

name: 'multipleChoice',

value: ['multipleFirst'],

onChange: (value) => {

console.log(`onChange event with value: ${value}`);

},

[

root.createComponent(BlockStack, undefined, [

root.createComponent(Choice, {id: 'multipleFirst'}, 'Gift message'),

root.createComponent(Choice, {id: 'multipleSecond'}, 'Gift wrapping'),

]),

],

);

const layout = root.createComponent(InlineStack, undefined, [

choiceList,

multipleChoiceList,

]);

root.appendChild(layout);

});

Preview

Examples

Basic ChoiceList

JS

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

export default extension('purchase.checkout.block.render', (root) => {
  const choiceList = root.createComponent(
    ChoiceList,
    {
      name: 'choice',
      value: 'first',
      onChange: (value) => {
        console.log(`onChange event with value: ${value}`);
      },
    },
    [
      root.createComponent(BlockStack, undefined, [
        root.createComponent(Choice, {id: 'first'}, 'Ship'),
        root.createComponent(Choice, {id: 'second'}, 'Pickup'),
      ]),
    ],
  );

  const multipleChoiceList = root.createComponent(
    ChoiceList,
    {
      name: 'multipleChoice',
      value: ['multipleFirst'],
      onChange: (value) => {
        console.log(`onChange event with value: ${value}`);
      },
    },
    [
      root.createComponent(BlockStack, undefined, [
        root.createComponent(Choice, {id: 'multipleFirst'}, 'Gift message'),
        root.createComponent(Choice, {id: 'multipleSecond'}, 'Gift wrapping'),
      ]),
    ],
  );

  const layout = root.createComponent(InlineStack, undefined, [
    choiceList,
    multipleChoiceList,
  ]);

  root.appendChild(layout);
});

React

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

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

function Extension() {
  return (
    <InlineStack>
      <ChoiceList
        name="choice"
        value="first"
        onChange={(value) => {
          console.log(
            `onChange event with value: ${value}`,
          );
        }}
      >
        <BlockStack>
          <Choice id="first">Ship</Choice>
          <Choice id="second">Pickup</Choice>
        </BlockStack>
      </ChoiceList>

      <ChoiceList
        name="choiceMultiple"
        value={['multipleFirst']}
        onChange={(value) => {
          console.log(
            `onChange event with value: ${value}`,
          );
        }}
      >
        <BlockStack>
          <Choice id="multipleFirst">
            Gift message
          </Choice>
          <Choice id="multipleSecond">
            Gift wrapping
          </Choice>
        </BlockStack>
      </ChoiceList>
    </InlineStack>
  );
}

Anchor to best-practicesBest Practices

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 relatedRelated

ComponentChoice

ComponentCheckbox

Was this page helpful?