Linter Rule: Disallow empty headings

Rule: html-no-empty-headings

Description

Disallow headings (h1, h2, etc.) with no accessible text content.

Rationale

Headings relay the structure of a webpage and provide a meaningful, hierarchical order of its content. If headings are empty or its text contents are inaccessible, this could confuse users or prevent them accessing sections of interest.

Examples

✅ Good

<h*>Heading Content</h*>

<h*><span>Text</span><h*>

<div role="heading" aria-level="1">Heading Content</div>

<h* aria-hidden="true">Heading Content</h*>

<h* hidden>Heading Content</h*>

🚫 Bad

<h1></h1>
Heading element `<h1>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<h2></h2>
Heading element `<h2>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<h3></h3>
Heading element `<h3>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<h4></h4>
Heading element `<h4>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<h5></h5>
Heading element `<h5>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<h6></h6>
Heading element `<h6>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<div role="heading" aria-level="1"></div>
Heading element `<div role="heading">` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

<h1><span aria-hidden="true">Inaccessible text</span></h1>
Heading element `<h1>` must not be empty. Provide accessible text content for screen readers and SEO. (html-no-empty-headings)

References

• <h1>–<h6>: The HTML Section Heading elements
• ARIA: heading role
• ARIA: aria-hidden attribute
• ARIA: aria-level attribute

Inspired by ember-template-lint