React fix guide
Fix Heading structure problems on React
Headings create an outline; random levels harm navigation.
This page ties the generic issue to how it usually shows up in React markup and tooling, then walks you through a fix and verification loop.
Verify on a live URL
Scan, fix, deploy, then rescan the same address to compare reports.
Main issue guide: Heading structure problems →
At a glance
Instructional
Skips levels
Page title
Subsection (styled as heading but wrong level)
Logical sequence
H1 Page title
H2 Section
H3 Subsection
Increase heading levels by one where possible; avoid picking tags for font size alone.
Where this comes from on React
Card titles using `h4` under an `h1` because the component hard-codes a level.
What this issue means
Why structure matters
Screen reader users jump by headings. Skipping from h1 to h3 breaks expectations; multiple h1s can be acceptable if scoped correctly.
How to fix on React
In React, trace the component that renders the failing node. Prefer native elements with visible text, `aria-label` only when no text exists, and test the built bundle—not just source.
How to fix
Use levels in order for the outline; style via CSS instead of picking headings for size.
Wrap repeated sections in landmarks (header, nav, main, footer) to aid navigation.
Common mistakes on React
- Hard-coded heading tag in Card.
- Marketing page with parallel `h1`s.
- Fixing Storybook but not production props.
- Conditional roles that differ between tests and prod.
How to verify the fix
- Run `npm run build && npm start` and test the production bundle.
- Tab through the component; check the accessibility tree in devtools.
- Rerun the scan on the deployed or staging URL.
Related: 1.3.1 Info and Relationships.
Same issue on other platforms
Related issues
Guides
Next steps
- Run a scan on staging or production.
- Re-read the main issue page for context and WCAG notes.
- React and Next.js accessibility hub for more platform resources.
TestAccessibility · React fix · localhost:3001