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

# Migrate to the Polaris choice component

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

`<s-choice>` must always be used inside an [`<s-choice-list>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list) parent.

***

## Updated properties

The following properties are different in the Polaris choice component.

### primary​Content, secondary​Content, and details

The previous `Choice` component used the `primaryContent`, `secondaryContent`, and `details` props to render content inside each choice. The Polaris choice component expresses these as children and slots.

| Previous prop | New pattern |
| - | - |
| `primaryContent` | `slot="details"` on the child element. |
| `secondaryContent` | `slot="secondary-content"` on the child element. |
| `details` | `slot="selected-content"` on the child element. |

These props are ignored on the default `Choice` `variant="base"`, so the previous code must use `variant="group"` for them to render. In the Polaris version, set `variant="block"` on the parent `<s-choice-list>` to get the equivalent layout.

## Migrating content props

##### Latest (Preact)

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

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

function Extension() {
return (
  <s-choice-list name="shipping" variant="block">
    <s-choice value="express" defaultSelected>
      Express shipping
      <s-text slot="details">Express shipping</s-text>
      <s-text slot="secondary-content">$15.00</s-text>
      <s-text slot="selected-content">Tracking included</s-text>
    </s-choice>
  </s-choice-list>
);
}
```

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

```tsx
import {
reactExtension,
ChoiceList,
Choice,
} from "@shopify/ui-extensions-react/checkout";

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

function Extension() {
return (
  <ChoiceList name="shipping" value="express" variant="group">
    <Choice
      id="express"
      primaryContent="Express shipping"
      secondaryContent="$15.00"
      details="Tracking included"
    >
      Express shipping
    </Choice>
  </ChoiceList>
);
}
```

***

## New properties

The Polaris choice component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`value`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list#choice-propertydetail-value) | `string` | Sets the value submitted with the form when the choice is selected. |
| [`selected`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list#choice-propertydetail-selected) | `boolean` | Sets the choice's selected state for controlled usage. |
| [`defaultSelected`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list#choice-propertydetail-defaultselected) | `boolean` | Sets the initial selected state for uncontrolled usage. |
| [`error`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/choice-list#choice-propertydetail-error) | `boolean` | Associates the choice with the error passed to the parent `<s-choice-list>`. |

***

## New slots

The Polaris choice component introduces a new slot for always-visible helper text alongside the choice.

| New slot | Description |
| - | - |
| `details` | Always-visible helper text for the choice. |

***

## Removed properties

### tertiary​Content

The previous `Choice` `tertiaryContent` prop is no longer supported. Use the `details` slot for additional content, or restructure the layout to use the other available slots.

***