---
title: HeadingGroup
description: >-
  Heading group controls the heading level of headings nested within it, like
  H1, H2, H3. Use a heading group whenever you use a heading to ensure the
  experience is the same for screen reader users.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/typography-and-content/headinggroup
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/typography-and-content/headinggroup.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# HeadingGroup

The heading group component controls the heading level of headings nested within it, managing the document outline hierarchy (H1, H2, H3, etc.).

Use heading group whenever you use a [Heading](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/typography-and-content/heading) to ensure screen reader users get the correct document structure. All content related to a heading should be nested within the same heading group.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Document structure**: Establish proper heading hierarchy for accessible navigation.
* **Nested sections**: Create subsections with automatically incremented heading levels.
* **Accessible outlines**: Ensure screen readers announce the correct document structure.
* **Content hierarchy**: Organize content into logical sections with appropriate heading levels.

***

## Examples

### Structure heading levels

Control the heading hierarchy for screen readers by nesting headings within a heading group. This example creates an accessible document outline.

## Structure heading levels

![A heading group component managing nested heading levels](https://shopify.dev/assets/assets/images/api/checkout-extensions/post-purchase/components/headinggroup-BAA52Ci5.png)

## Structure heading levels

##### React

```tsx
import {
  reactExtension,
  HeadingGroup,
  Heading,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <>
      <Heading>Heading <h1></Heading>

      <HeadingGroup>
        <Heading>Heading <h2></Heading>

        <HeadingGroup>
          <Heading>Heading <h3></Heading>
        </HeadingGroup>
      </HeadingGroup>
    </>
  );
}
```

##### JS

```js
import {
  extension,
  HeadingGroup,
  Heading,
  View,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const headingGroup = root.createComponent(View, undefined, [
    root.createComponent(Heading, undefined, 'Heading <h1>'),
    root.createComponent(HeadingGroup, undefined, [
      root.createComponent(Heading, undefined, 'Heading <h2>'),
      root.createComponent(HeadingGroup, undefined, [
        root.createComponent(Heading, undefined, 'Heading <h3>'),
      ]),
    ]),
  ]);

  root.appendChild(headingGroup);
});
```

***

## Best practices

* **Always pair with Heading**: Every heading should be inside a heading group for proper accessibility.
* **Nest for hierarchy**: Place heading groups inside other heading groups to create nested heading levels.
* **Keep structure flat when possible**: Avoid deeply nested heading groups as they create complex document outlines.

***