---
title: Migrate to the Polaris select component
description: >-
  Learn how to migrate the Select component to Polaris web components in
  checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/select
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/select.md
---

# Migrate to the Polaris select component

The Polaris select component renders a dropdown for selecting a single value from a list of options. It replaces the previous [`Select`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/forms/select) component and is available as [`<s-select>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/select) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris select component.

### options

The previous `Select` `options` array prop has been replaced with `<s-option>` child elements (documented under [`<s-select>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/select)). Each option becomes an `<s-option>` child with a `value` attribute; the visible text goes between the tags (as children). The old `options[].label` string becomes that child text.

## Migrating options from array to children

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-select label="Country" name="country">
      <s-option value="ca">Canada</s-option>
      <s-option value="us">United States</s-option>
      <s-option value="mx">Mexico</s-option>
    </s-select>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Select,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  return (
    <Select
      label="Country"
      name="country"
      options={[
        {value: 'ca', label: 'Canada'},
        {value: 'us', label: 'United States'},
        {value: 'mx', label: 'Mexico'},
      ]}
    />
  );
}
```

To disable individual options, set the `disabled` attribute on the `<s-option>` element:

```tsx
<s-select label="Shipping method" name="shipping">
  <s-option value="standard">Standard (3-5 days)</s-option>
  <s-option value="express">Express (1-2 days)</s-option>
  <s-option value="overnight" disabled>Overnight</s-option>
</s-select>
```

### on​Change

The previous `Select` `onChange` prop is now handled through the standard [`change`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/select#events-propertydetail-change) event. In Preact, use `onChange` and access the value from `event.currentTarget.value`.

## Migrating onChange

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const [size, setSize] = useState('medium');

  return (
    <s-select
      label="Size"
      name="size"
      value={size}
      onChange={(event) => setSize(event.currentTarget.value)}
    >
      <s-option value="small">Small</s-option>
      <s-option value="medium">Medium</s-option>
      <s-option value="large">Large</s-option>
    </s-select>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {useState} from 'react';
import {
  reactExtension,
  Select,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  const [size, setSize] = useState('medium');

  return (
    <Select
      label="Size"
      name="size"
      value={size}
      onChange={(value) => setSize(value)}
      options={[
        {value: 'small', label: 'Small'},
        {value: 'medium', label: 'Medium'},
        {value: 'large', label: 'Large'},
      ]}
    />
  );
}
```

***

## Removed properties

### readonly

The Polaris select component no longer supports `readonly`. Use `disabled` instead if you need to prevent interaction.

**Note:**

`disabled` changes the visual appearance and excludes the field from form submission. If you need to display read-only information, consider using a text component instead of a select.

***