---
title: Migrate to the Polaris section component
description: >-
  Learn how to migrate the HeadingGroup component to the Polaris section web
  component in checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/heading-group
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/heading-group.md
---

# 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`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/components/titles-and-text/headinggroup) component and is available as [`<s-section>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/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>`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/components/titles-and-text/heading) component. `<s-section>` preserves that automatic heading hierarchy and adds structural properties for labelling the section directly.

**Visual styling:**

Unlike `HeadingGroup`, `<s-section>` has its own visual styling that follows the merchant's branding. `<s-section>` accepts only [`heading`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/section#properties-propertydetail-heading), [`accessibilityLabel`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/section#properties-propertydetail-accessibilitylabel), and [`id`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/section#properties-propertydetail-id).

***

## New properties

The Polaris section component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`heading`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/section#properties-propertydetail-heading) | `string` | A title that describes the content of the section. |
| [`accessibilityLabel`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/section#properties-propertydetail-accessibilitylabel) | `string` | A label announced by assistive technologies when no `heading` is provided. |
| [`id`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/section#properties-propertydetail-id) | `string` | A unique identifier for the element. |

## Migrating HeadingGroup to s-section

##### Latest (Preact)

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

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

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

### Nested 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.

## Nesting sections to increment heading level

##### Latest (Preact)

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

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

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

***