Migrate to the Polaris choice component

The Polaris choice component renders a single selectable option inside a choice list. It replaces the previous Choice component and is available as <s-choice> in API versions 2025-10 and newer.

<s-choice> must always be used inside an <s-choice-list> parent.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris choice component.

Anchor to primaryContent, secondaryContent, and detailsprimaryContent, secondaryContent, 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.

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.

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

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

Anchor to New propertiesNew properties

The Polaris choice component introduces the following new properties:

Anchor to New slotsNew slots

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

Anchor to Removed propertiesRemoved properties

Anchor to tertiaryContenttertiaryContent

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.