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 component and is available as <s-select> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris select component.

Anchor to optionsoptions

The previous Select options array prop has been replaced with <s-option> child elements (documented under <s-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.

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>
  );
}

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:

Anchor to onChangeonChange

The previous Select onChange prop is now handled through the standard change event. In Preact, use onChange and access the value from event.currentTarget.value.

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>
  );
}

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'},
      ]}
    />
  );
}

Anchor to Removed propertiesRemoved properties

Anchor to readonlyreadonly

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