---
title: Migrate OptionList from Polaris React
description: >-
  Replace Polaris React OptionList with s-choice-list for visible choices or
  s-select for a compact single choice.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/option-list
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/option-list.md
api_name: app-home
---

# Migrate Option​List 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.

***

## Migrate visible options

## Migrating checkout options

##### Polaris web components

```html
<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

```tsx
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'},
  ]}
/>
```

***

## Replace Option​List 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.

***

## Test 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.

***

## Remove 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.

***

## Related guidance

* [Choice list component](https://shopify.dev/docs/api/app-home/web-components/forms/choice-list)
* [Select component](https://shopify.dev/docs/api/app-home/web-components/forms/select)
* [Migrate Listbox from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/listbox)

***