---
title: Migrate to the Polaris switch component
description: >-
  Learn how to migrate the Switch 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/switch
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/switch.md
---

# Migrate to the Polaris switch component

The Polaris switch component provides a toggle control for binary options. It replaces the previous [`Switch`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/forms/switch) component and is available as [`<s-switch>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris switch component.

### on​Change

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

## Migrating onChange

##### Latest (Preact)

```jsx
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);
      }}
    />
  );
}
```

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

```jsx
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)}
    />
  );
}
```

### value

The previous `Switch` `value` prop was a `boolean` alias for `checked`, used to drive the controlled checked state. On the Polaris switch, use [`checked`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-checked) for controlled usage, or [`defaultChecked`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-defaultchecked) to set only the initial state for uncontrolled usage.

## Migrating value

##### Latest (Preact)

```jsx
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)}
    />
  );
}
```

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

```jsx
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`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-value) as a `string` used as the form submission value, and it's only submitted when the switch is checked. Pair it with [`name`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-name) to participate in form submission:

## Using value for form submission

```jsx
<s-switch
  label="Enable notifications"
  name="notifications"
  value="enabled"
/>
```

***

## Removed properties

### toggles

The Polaris switch component no longer supports `toggles`. Use [`command="--toggle"`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-command) with [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-commandfor) instead, targeting the element you want to show or hide when the switch is toggled.

| Previous value | New pattern |
| - | - |
| `toggles="<id>"` | Use `command="--toggle"` with `commandFor="<id>"` on `<s-switch>`. |

## Migrating toggles to command and commandFor

##### Latest (Preact)

```tsx
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>
    </>
  );
}
```

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

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

***

## New properties

The Polaris switch component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-command) | `'--auto'` \| `'--toggle'` \| `'--show'` \| `'--hide'` | Command to execute when toggled. |
| [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-commandfor) | `string` | ID of the element to target. |
| [`defaultChecked`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/switch#properties-propertydetail-defaultchecked) | `boolean` | Default checked state for uncontrolled usage. |

***