Migrate OptionList from Polaris React

Replace Polaris React OptionList with s-choice-list when choices should remain visible. Use s-select for a compact single choice. Preserve group labels, stable values, multiple selection, disabled options, and validation.

Anchor to Migrate visible optionsMigrate visible options

Migrating checkout options

<s-choice-list label="Checkout options" name="checkout" multiple>

<s-choice value="shipping" selected>

Use the shipping address as the billing address by default

<s-text slot="details">

Reduces the number of fields required to check out. The billing address

can still be edited.

</s-text>

</s-choice>

<s-choice value="confirmation">

Require a confirmation step

<s-text slot="details">

Customers must review their order details before purchasing.

</s-text>

</s-choice>

</s-choice-list>

import {OptionList} from '@shopify/polaris';

<OptionList

title="Checkout options"

allowMultiple

selected={selected}

onChange={setSelected}

options={[

{value: 'shipping', label: 'Use shipping address for billing'},

{value: 'confirmation', label: 'Require a confirmation step'},

]}

Polaris web components

<s-choice-list label="Checkout options" name="checkout" multiple>
  <s-choice value="shipping" selected>
    Use the shipping address as the billing address by default
    <s-text slot="details">
      Reduces the number of fields required to check out. The billing address
      can still be edited.
    </s-text>
  </s-choice>
  <s-choice value="confirmation">
    Require a confirmation step
    <s-text slot="details">
      Customers must review their order details before purchasing.
    </s-text>
  </s-choice>
</s-choice-list>

Polaris React

import {OptionList} from '@shopify/polaris';

<OptionList
  title="Checkout options"
  allowMultiple
  selected={selected}
  onChange={setSelected}
  options={[
    {value: 'shipping', label: 'Use shipping address for billing'},
    {value: 'confirmation', label: 'Require a confirmation step'},
  ]}
/>

Preview

Anchor to Replace OptionList propertiesReplace OptionList properties

Polaris React	Polaris web components	Migration notes
`title`	`label` on `s-choice-list` or `s-select`	Keep a label that describes the decision.
`options`	Explicit `s-choice` or `s-option` children	Keep stable values separate from translated labels.
`sections`	Separate labelled choice lists, or simplify the information architecture	Don't put headings inside a compact select.
`allowMultiple`	`multiple` on `s-choice-list`	A select destination should remain single-choice.
`selected`	`values` on `s-choice-list` or `value` on `s-select`	Keep one source of controlled state.
`onChange(values)`	`onChange(event)`	Read `values` from a choice list or `value` from a select.

Map per-option disabled to the child control. Put option help text in s-text slot="details" inside the corresponding s-choice. If the old list contains media, actions, or rich arbitrary content, use a resource-list pattern instead of forcing it into a form control.

Anchor to Test the migrationTest the migration

Select and clear each option with keyboard and pointer input.
Verify single and multiple values submit under the intended field name.
Exercise option and group disabled states.
Trigger group validation and verify the error is announced.
Test long translated labels and details at narrow widths.

Anchor to Remove Polaris ReactRemove Polaris React

Remove OptionList, option and section descriptor builders, and callback adapters after every call site uses a supported control or pattern. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Related guidanceRelated guidance

Was this page helpful?