Alert - Skipped heading level
- WAVE Category: Alert
- WAVE Alert: Skipped heading level
Page Content Status
- WAVE Error guidance text
- Example of a DOM Snippet Generated From WAVE Tool
- Project Team Error guidance
- Project Team Page Details
- Project Team Issue and PR details
- Project Team Solution
- Credits/Authors
WAVE Alert guidance
WAVE Tool's Reference material on Skipped heading level may not specifically address your problem. We provide it here for optional reading.
Click to see WAVE Tool Reference
This content added 2026-02-26. Check for updated guidance at: https://wave.webaim.org/api/docs?format=html#heading_skipped
WAVE Category
Alerts
WAVE Error
Skipped heading level
What It Means
A heading level is skipped.
Why It Matters
Headings provide document structure and facilitate keyboard navigation by users of assistive technology. These users may be confused or experience difficulty navigating when heading levels are skipped.
What To Do
Restructure the document headings to ensure that heading levels are not skipped.
The Algorithm... in English
A heading level is skipped (e.g., an
<h1>is followed by an<h3>, with no intermediate<h2>). Note that an<h1>is not required to be the first heading within the document.Standards and Guidelines
Example of a DOM Snippet Generated From WAVE Tool
Project Team Error guidance
The following material covers how the Project Team has provided a solution to the Skippped heading level WAVE alert.
Project Page Details 1
- Project Page name: About Page
- Project Dev URL: https://tdm-dev.azurewebsites.net/about
- Requires sign in: FALSE
- Required User Role: All Users
- Can access page directly from URL: TRUE
- Accepts URL parameters: FALSE
Project Team Issue and PR details 1
- Related GitHub Issue(s):
- https://github.com/hackforla/tdm-calculator/issues/2960
- Related Pull Request(s):
- https://github.com/hackforla/tdm-calculator/pull/3033
- React Component(s)
- client/src/components/About/DefaultView.jsx
Project Team Solution
What is the specific problem that was occurring?
The issues above were caused by a skip in sequential heading level within a page's html. For example, if a page had a <h1> and <h3>, but no <h2>. This is problematic for assistive technology users because heading levels serve as a table of contents for understanding the structure of information on a web page. When a heading level is skipped, a user may assume there is missing information or that there are no further heading levels to explore when they encounter a heading level with no content. It is a major break in expected behavior and is disruptive for a user's ability to understand a page quickly`
What is the proposed solution to this problem?
This can be resolved by updated the heading levels so that no levels are skipped. In the example provided above, the <h3> heading should be updated to <h2>. In addition, we should double check that this update does not create a new skipped heading level for the rest of the page and if so, update accordingly.`
Step-By-Step Guide
N/A
Other Technical Details
N/A
Code Snippet With Solution
client/src/components/About/DefaultView.jsx
```jsx
[const DefaultView = ({ aboutList }) => {
const classes = useStyles();
if (!aboutList || aboutList?.length === 0) {
return null;
}
return (
<>
{aboutList.map(about => (
<div key={about.id}>
<h2 className={classes.subheading}>{about.title}</h2>
<Interweave
transform={TransformExternalLink}
content={about.content}
/>
</div>
))}
</>
);
};]
```
Why the Fix Works
- This fix because it removes the gap in sequential heading levels within a single page.
Where this solution is applicable
- Any page of the website since all pages should have an h1 and then require sequential heading levels for any subheadings.
Screenshots of WAVE Error
1. WAVE tool showing skipped heading level error
Credits/Authors
- @experimentsinhonesty
- @Rabia2219
- @ColinBuyck