Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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 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

Anchor to ExamplesExamples

Anchor to Structure heading levelsStructure 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

Structure heading levels

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>

<Heading>Heading <h2></Heading>

<Heading>Heading <h3></Heading>

</HeadingGroup>

</>

);

}

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

});

React

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

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

Anchor to Best practicesBest 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.

Was this page helpful?