Learn Measure Blog About

Heading elements are not in a sequentially-descending order

Heading elements are not in a sequentially-descending order

• Updated
Appears in: Accessibility audits

Screen readers have commands to quickly jump between headings or to specific landmark regions. In fact, a survey of screen reader users found that they most often navigate an unfamiliar page by exploring the headings.

By using correct heading and landmark elements, you can dramatically improve the navigation experience on your site for users of assistive technologies.

How the Lighthouse heading levels audit fails #

Lighthouse flags pages whose headings skip one or more levels:

Lighthouse audit showing headings that skip levels

For example, using an <h1> element for your page title and then using <h3> elements for the page's main sections will cause the audit to fail because the <h2> level is skipped:

<h1>Page title</h1>
  <h3>Section heading 1</h3>
  …
  <h3>Section heading 2</h3>
  …

The Lighthouse Accessibility score is a weighted average of all the accessibility audits. See the Lighthouse accessibility scoring post for more information.

How to fix poorly structured headings #

  • Make all heading elements follow a logical, numerical order that reflects the structure of your content.
  • Make sure your heading text clearly conveys the content in the associated section.

For example:

<h1>Page title</h1>
<section>
  <h2>Section Heading</h2>
  …
    <h3>Sub-section Heading</h3>
</section>

One way to check your heading structure is to ask, "If someone created an outline of my page using only the headings, would it make sense?"

You can also use tools like Microsoft's Accessibility Insights extension to visualize your page structure and catch out-of-order heading elements.

Caution: Less experienced developers sometimes skip heading levels to achieve a desired visual style. For example, they may use an <h3> element because they feel the <h2> text is too large. This is considered an anti-pattern. Instead, use a correctly sequenced heading structure and use CSS to visually style the headings as desired.

See the Headings and landmarks post for more information.

Resources #

Last updated: Improve article