page-has-heading-one

Page should have a level-one heading

Checks that the page has at least one level-one heading (<h1> or role="heading" with aria-level="1").

Applies to. Applicable to any HTML document with a <body> element that is a page of its own (a document shown in a frame is not): "does the page have an h1" is a whole-page concern, matching bypass-blocks-present's pattern of evaluating the document directly. Not while a modal dialog is open: the rest of the page is inert then, so the scan sees the dialog, not the page. A custom element whose ElementInternals give it the heading role (this.attachInternals().role) and level 1 (its aria-level attribute or its internals' ariaLevel) counts as an <h1>. A native <hx> marked role="none" or "presentation" is still a heading when it can take focus or carries a global ARIA attribute, as WAI-ARIA's presentational roles conflict resolution has browsers ignore that role then. A native <hx> with a valid aria-level (a positive integer) has that level, as browsers expose it: <h2 aria-level="1"> is a level-one heading and <h1 aria-level="2"> is not, as heading-order reads them.

Expectation. At least one heading with level 1 exists (native <h1>, or role="heading" with aria-level="1"). A page with no top-level heading has no clear entry point for assistive technology users navigating by heading.

Examples

<body>
  <h1>Page title</h1>
</body>

<body>
  <h2>Section</h2>
  <p>No top-level heading anywhere on the page.</p>
</body>

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

View source