How to fix heading order on Headless / Custom (I build in code)

Steps for Headless / Custom (I build in code)

1. Run the axe-core library or the axe DevTools CLI against your pages to get a full list of heading-order violations with exact DOM locations.
2. In your component library, audit every component that renders a heading (e.g., ProductTitle, SectionHeader, CardTitle) — these often hard-code a heading level (e.g., always <h3>) regardless of context.
3. Refactor heading components to accept a 'level' prop (e.g., level={2}) that maps to the correct HTML tag dynamically, e.g. in React: const Tag = `h${level}`; return <Tag className={styles.heading}>{children}</Tag>;
4. Update each page template to pass the correct level based on the component's position in the page hierarchy — the page-level H1 is typically the product or page name; section titles are H2; subsections are H3.
5. Add an automated axe-core test (e.g., via jest-axe or Cypress-axe) to your CI pipeline to prevent regressions.

What is heading order?

HTML headings (H1 through H6) are not just visual styling — they form an invisible outline of your page that screen readers and search engines read to understand your content structure. "Heading order invalid" means your page skips heading levels (for example, jumping from an H1 straight to an H4, or using an H3 before an H2), or uses headings out of sequence. Think of headings like the chapters and sub-chapters of a book: if you skip from Chapter 1 straight to Sub-sub-section 4, the reader loses the thread. The fix is to ensure every heading on every page flows in a strict, unbroken hierarchy: one H1 (the page title), then H2s for major sections, then H3s for sub-sections within those, and so on — never skipping a level on the way down.

Screen reader users — people who are blind or have low vision — navigate pages almost exclusively by jumping between headings. A broken heading order disorients them, makes your store harder or impossible to use, and can expose you to accessibility lawsuits under the ADA (USA), AODA (Canada), EAA (EU), and similar laws that are increasingly enforced against ecommerce businesses. Search engines like Google also use heading structure to understand what a page is about and which content matters most; a well-structured heading hierarchy reinforces your keyword relevance signals and can improve organic rankings. Finally, fixing heading order removes a WCAG 2.1 Level AA failure (Success Criterion 1.3.1, "Info and Relationships"), which is the baseline standard most accessibility audits and legal compliance frameworks reference.

See the complete Heading order guide for every platform and the full background.