• June 30, 2025

Ensure Page Contains a Level-One Heading

Rule ID: page-has-heading-one
Ruleset: axe-core 4.10
User Impact: Moderate
Guidelines: Deque Best Practice

How to Fix the Problem

To ensure an accessible structure for all users, especially those relying on assistive technologies:

• Include a level-one heading (<h1>) at the beginning of the main content on every page or its frames. This heading should describe the primary purpose or topic of the page.

• Only one <h1> per document is typically recommended to clearly indicate the start of the content hierarchy. Use <h2> for subsections, <h3> for subsections within those, and so on.

• If your page includes iframes, try to ensure that the headings within the iframe integrate into the existing heading hierarchy of the parent page. For example:

  • If the parent document starts with <h1>, the iframe content might start with <h2> (if directly related) or <h3> (if nested deeper).

• If control over iframe content is not possible (e.g., it’s from a third-party source), do your best to ensure at least the parent page’s structure follows best practices. Though not strictly required, matching heading structures across parent and iframe content is still preferred for clarity.

Example:

And in the iframe-content.html:

Why it Matters

Proper heading structure provides essential navigational cues for screen reader users:

• <h1> serves as a landmark for the main content of the page, allowing users to jump directly to the core information.

• Without an <h1>, users relying on screen readers must manually navigate or listen through more of the page, which can be time-consuming and frustrating.

• Unlike sighted users, blind users can’t scan a page visually. They depend on keyboard shortcuts and heading navigation to understand layout and content hierarchy quickly.

• Using a logical heading order not only helps screen readers but also benefits all users by improving content structure and readability.

Rule Description

This rule ensures that the page, or at least one of its frames, contains a level-one heading (<h1>). This heading must appear before the main content to allow efficient keyboard navigation through the document’s heading structure.

The Algorithm (in simple terms)

• Check the document (or each frame) for at least one element that matches either:

  • <h1> that does not have a role attribute.

  • An element with role="heading" and aria-level="1".

• If none are found, the rule fails.