Upgrade to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use Polaris web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension and avoid being blocked from updating your extension after October 1st 2026.

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 Use casesUse 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.

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?