Next.js fix guide
Fix Heading structure problems on Next.js
Headings create an outline; random levels harm navigation.
This page ties the generic issue to how it usually shows up in Next.js 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 Next.js
Layout vs page both emit `h1`; coordinate shells and route content.
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 Next.js
In Next.js, verify both server and client components: hydration can change roles/names. Use `next/image` with meaningful `alt`, and ensure dynamic imports do not drop focus management.
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 Next.js
- Layout `h1` plus page `h1`.
- Assuming dev overlay errors match production a11y tree.
- Ignoring dynamic imports that shift structure.
How to verify the fix
- Test the production build (focus and hydration differ from dev).
- Verify both mobile and desktop layouts if they diverge.
- Rerun the scan; compare rule counts on the same path.
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 · Next.js fix · localhost:3001