All rules

Sheath rule

a11y-no-empty-headings

Headings must have text content.
Package
Core
Category
Accessibility
Default severity
error by default
Auto-fix
Manual fix

#Why

Headings should have text content to be meaningful for screen reader users. Empty headings create confusing navigation landmarks because screen readers announce them as headings but provide no information about the section content.

#Examples

#Bad

<!-- Empty heading -->

<h1></h1>



<!-- Whitespace-only heading -->

<h2>   </h2>



<!-- Heading with only non-text elements -->

<h3><span></span></h3>



<!-- Empty heading for styling purposes -->

<h4 class="divider"></h4>

#Good

<!-- Headings with text content -->

<h1>Welcome to Our Site</h1>

<h2>About Us</h2>

<h3>Our Services</h3>



<!-- Heading with icon and text -->

<h2><i class="icon-star"></i> Featured Products</h2>



<!-- Heading with image that has alt text -->

<h2><img src="logo.png" alt="Company Name"></h2>



<!-- Visually hidden text for screen readers -->

<h2><span class="sr-only">Section Title</span></h2>

#Notes

  • Text inside hidden, inert, aria-hidden="true", script, style, or template descendants does not make a heading non-empty.
  • If you need a visual divider, use CSS borders or <hr> instead of empty headings
  • Headings should describe the content of their section
  • Screen readers use headings for document navigation
  • Empty headings break the document outline and confuse users

#References

#Related Rules