Migrate to the Polaris section component

The Polaris section component groups related content with an optional heading and increments the nested heading level. It replaces the previous HeadingGroup component and is available as <s-section> in API versions 2025-10 and newer.

The previous HeadingGroup didn't accept any props — it was a semantic wrapper that incremented the level of any nested <Heading> component. <s-section> preserves that automatic heading hierarchy and adds structural properties for labelling the section directly.

Anchor to New propertiesNew properties

The Polaris section component introduces the following new properties:

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

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

function Extension() {
  return (
    <s-section heading="Order summary">
      <s-text>Your order includes free shipping.</s-text>
    </s-section>
  );
}

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

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

function Extension() {
  return (
    <HeadingGroup>
      <Heading>Order summary</Heading>
      <Text>Your order includes free shipping.</Text>
    </HeadingGroup>
  );
}

Anchor to Nested sectionsNested sections

HeadingGroup was most useful when nested — each level pushed children one heading level deeper. <s-section> does the same. Headings inside an outer section render at one level, and headings inside a nested section render one level deeper, without setting heading levels manually.

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

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

function Extension() {
  return (
    <s-section heading="Order summary">
      <s-text>Your order is ready.</s-text>
      <s-section heading="Shipping details">
        <s-text>Standard shipping, 3–5 business days.</s-text>
      </s-section>
    </s-section>
  );
}

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

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

function Extension() {
  return (
    <HeadingGroup>
      <Heading>Order summary</Heading>
      <Text>Your order is ready.</Text>
      <HeadingGroup>
        <Heading>Shipping details</Heading>
        <Text>Standard shipping, 3–5 business days.</Text>
      </HeadingGroup>
    </HeadingGroup>
  );
}