Migrate to the Polaris switch component

The Polaris switch component provides a toggle control for binary options. It replaces the previous Switch component and is available as <s-switch> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris switch component.

Anchor to onChangeonChange

The previous Switch onChange prop now receives an Event instead of the new boolean value. Read the checked state from event.currentTarget.checked.

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

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

function Extension() {
  return (
    <s-switch
      label="Enable notifications"
      onChange={(event) => {
        console.log('Checked:', event.currentTarget.checked);
      }}
    />
  );
}

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

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

function Extension() {
  return (
    <Switch
      label="Enable notifications"
      onChange={(value) => console.log('Checked:', value)}
    />
  );
}

Anchor to valuevalue

The previous Switch value prop was a boolean alias for checked, used to drive the controlled checked state. On the Polaris switch, use checked for controlled usage, or defaultChecked to set only the initial state for uncontrolled usage.

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 [isEnabled, setIsEnabled] = useState(true);

  return (
    <s-switch
      label="Enable notifications"
      checked={isEnabled}
      onChange={(event) => setIsEnabled(event.currentTarget.checked)}
    />
  );
}

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

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

function Extension() {
  const [isEnabled, setIsEnabled] = useState(true);

  return (
    <Switch
      label="Enable notifications"
      value={isEnabled}
      onChange={setIsEnabled}
    />
  );
}

The Polaris switch repurposes value as a string used as the form submission value, and it's only submitted when the switch is checked. Pair it with name to participate in form submission:

Anchor to Removed propertiesRemoved properties

Anchor to togglestoggles

The Polaris switch component no longer supports toggles. Use command="--toggle" with commandFor instead, targeting the element you want to show or hide when the switch is toggled.

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

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

function Extension() {
  return (
    <>
      <s-switch
        label="Show gift options"
        command="--toggle"
        commandFor="gift-options"
      />
      <s-details id="gift-options">
        <s-text-field label="Gift message" />
      </s-details>
    </>
  );
}

import {
  Disclosure,
  Switch,
  TextField,
  View,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  return (
    <Disclosure>
      <Switch label="Show gift options" toggles="gift-options" />
      <View id="gift-options">
        <TextField label="Gift message" />
      </View>
    </Disclosure>
  );
}

Anchor to New propertiesNew properties

The Polaris switch component introduces the following new properties: