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

# Migrate to the Polaris checkbox component

The Polaris checkbox component renders a checkbox input. It replaces the previous [`Checkbox`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/forms/checkbox) component and is available as [`<s-checkbox>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris checkbox component.

### on​Change

The previous `Checkbox` `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-checkbox
      label="I agree to the terms"
      onChange={(event) => {
        console.log('Checked:', event.currentTarget.checked);
      }}
    />
  );
}
```

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

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

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

function Extension() {
  return (
    <Checkbox onChange={(value) => console.log('Checked:', value)}>
      I agree to the terms
    </Checkbox>
  );
}
```

### value

The previous `Checkbox` `value` prop was a `boolean` alias for `checked`, used to drive the controlled checked state. On the Polaris checkbox, use [`checked`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-checked) for controlled usage, or [`defaultChecked`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#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 [isChecked, setIsChecked] = useState(true);

  return (
    <s-checkbox
      label="I agree to the terms"
      checked={isChecked}
      onChange={(event) => setIsChecked(event.currentTarget.checked)}
    />
  );
}
```

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

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

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

function Extension() {
  const [isChecked, setIsChecked] = useState(true);

  return (
    <Checkbox value={isChecked} onChange={setIsChecked}>
      I agree to the terms
    </Checkbox>
  );
}
```

The Polaris checkbox repurposes [`value`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-value) as a `string` used as the form submission value, and it's only submitted when the checkbox is checked. Pair it with [`name`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-name) to participate in form submission:

## Using value for form submission

```jsx
<s-checkbox
  label="I agree to the terms"
  name="terms"
  value="accepted"
/>
```

***

## New properties

The Polaris checkbox component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-command) | `'--auto'` \| `'--show'` \| `'--hide'` \| `'--toggle'` | Sets the action to run on the target component when the checkbox is activated. |
| [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-commandfor) | `string` | Sets the ID of the target component for the command. |
| [`defaultChecked`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-defaultchecked) | `boolean` | Sets the initial checked state for uncontrolled usage. |
| [`label`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-label) | `string` | Sets the checkbox's visible label. Replaces the previous `children` pattern. For rich label content (text with inline links), use the `label` slot instead — see [children](#children) below. |
| [`required`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-required) | `boolean` | Adds semantic meaning that the field needs a value. It doesn't trigger automatic validation or display an error — set the [`error`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-error) property to present an error when the checkbox is empty. |

***

## Removed properties

### children

The previous `Checkbox` component accepted any element as children to render the visible label, which allowed composing the label from text, inline components, or formatting. The Polaris checkbox doesn't render children. Migrate based on the label content:

* **Plain string labels** — use the [`label`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-label) property.
* **Rich label content** (text combined with inline [`<s-link>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link)) — provide an `<s-text>` element with `slot="label"`. When present, the slot takes precedence over the `label` property.

The `label` slot's direct child **must be a single `<s-text>`** element. Inside that `<s-text>`, you can include text and inline `<s-link>` elements — any other elements are stripped to keep the label safe to render inside the underlying `<label>` element.

## Migrating children to label (string)

##### Latest (Preact)

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

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

function Extension() {
  return <s-checkbox label="I agree to the terms" />;
}
```

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

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

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

function Extension() {
  return <Checkbox>I agree to the terms</Checkbox>;
}
```

## Migrating children to the label slot (rich content)

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-checkbox>
      <s-text slot="label">
        I agree to the <s-link href="/terms">terms</s-link>
      </s-text>
    </s-checkbox>
  );
}
```

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

```jsx
import {
  reactExtension,
  Checkbox,
  Link,
  Text,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  return (
    <Checkbox>
      <Text>
        I agree to the <Link to="/terms">terms</Link>
      </Text>
    </Checkbox>
  );
}
```

### toggles

The previous `Checkbox` `toggles` prop has been replaced by the [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-command) and [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/checkbox#properties-propertydetail-commandfor) props. Point `commandFor` at an [`<s-details>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details) element, and the checkbox will expand or collapse it when toggled.

| Previous pattern | New pattern |
| - | - |
| `toggles="gift-message"` | `command="--toggle"` + `commandFor="gift-message"` targeting an [`<s-details>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details). |

## Migrating toggles to command

##### Latest (Preact)

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

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

function Extension() {
  return (
    <>
      <s-checkbox
        label="Add a gift message"
        command="--toggle"
        commandFor="gift-message"
      />
      <s-details id="gift-message">
        <s-text-field label="Gift message" />
      </s-details>
    </>
  );
}
```

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

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

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

function Extension() {
  return (
    <Disclosure>
      <Checkbox toggles="gift-message">Add a gift message</Checkbox>
      <View id="gift-message">
        <TextField label="Gift message" />
      </View>
    </Disclosure>
  );
}
```

***