A page must contain only one <h1> heading

Rule ID: page-has-heading-one
Ruleset: axe-core 3.0
User Impact: Moderate
WCAG: Best practice

Learn Web Accessibility

Subscribe to our extensive curriculum of online self-paced courses

Compliance Data & Impact

User Impact

Disabilities Affected

  • Sighted Keyboard Users
  • Blindness
  • Low Vision
  • Deafblindness

Requirement(s)

  • Best Practice

WCAG Success Criteria

  • Not specified or not applicable

Section 508 Guidelines

  • Not specified or not applicable

How to Fix the Problem

Ensure that the page, or at least one of its frames contains a level-one heading.

Generally, it is a best practice to ensure that the beginning of a page's main content starts with <h1>, and also to ensure that the page has only one <h1>.

Usually the best practice is to start the main content of a web page with a level 1 heading (<h1>), with no other headings before this high level heading. The sub-sections of the page should each be marked as level 2 headings (<h2>). If there are sub-sections within the level 2 sections, they should be marked as level 3 (<h3>) and so on.

The heading hierarchy of an iframe SHOULD be designed to fit within the heading hierarchy of the parent document, if possible. If you have control over the content of the embedded document in the iframe, the best practice is to fit the iframe heading hierarchy into the proper place within the existing heading hierarchy of the parent page. If the parent document is structured with a single <h1> at the top of the content (this is a recommended best practice), the <iframe> ought to take this into account, and not start with another <h1>. The <iframe> document ought to start with <h2> if the content is a direct child of the first heading on the page, or if it is a child of a level 2 heading, then the first heading of the iframe should be <h3>, and so on.

When iframes contain content from third-party web sites — as is often the case — it is not always possible to control the heading hierarchy. Because of the lack of control in these situations, the guidelines don't strictly require the heading hierarchies of the two documents to match, but it would still be better if they did.

Why this is Important

Screen reader users can use keyboard shortcuts to navigate directly to the first <h1>, which, in principle, should allow them to jump directly to the main content of the web page. If there is no <h1>, or if the <h1> appears somewhere other than at the start of the main content, screen reader users will have to listen to more of the web page to understand its structure, wasting valuable time.

Keep in mind that blind users can't just look at a web page and immediately understand its layout the way that a visual user can. Visual users can take in a lot of information about the page layout without having to read all of the content. Blind users don't have that luxury. Screen readers read in a linear fashion, which means listening to the entire web page, unless there is some other convenient way to get a "glimpse" of the page's layout and structure. It turns out that headings are a way to do that. Screen reader users can use keyboard shortcuts to navigate through the heading structure of a document.

Rule Description

Ensures that the page, or at least one of its frames contains an <h1> that appears before the start of the main content to allow screen reader users to use keyboard shortcuts to navigate the heading structure instead of wasting time listening to more of the web page to understand its structure.

The Algorithm (in simple terms)

This rule finds all elements which match the following selector and verifies that there is at least one: h1:not([role]), [role="heading"][aria-level="1"]

Resources

Other Resources

You may also want to check out these other resources.

Refer to the complete list of axe 3.0 rules.