useHeadingContent (HTML)

Summary

Rule available since: v2.5.0
Diagnostic Category: lint/a11y/useHeadingContent
This rule is recommended, meaning it is enabled by default.
This rule doesn’t have a fix.
The default severity of this rule is error.
Sources:
- Inspired from jsx-a11y/heading-has-content
- Same as @html-eslint/no-empty-headings

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "a11y": {
5
        "useHeadingContent": "error"
6
      }
7
    }
8
  }
9
}

Description

Enforce that heading elements (h1, h2, etc.) have content and that the content is accessible to screen readers.

Accessible means that it is not hidden using the aria-hidden attribute. All headings on a page should have content that is accessible to screen readers to convey meaningful structure and enable navigation for assistive technology users.

Examples

Invalid

1
<h1></h1>

code-block.html:1:1 lint/a11y/useHeadingContent ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide screen reader accessible content when using heading elements.
  
  > 1 │ <h1></h1>
      │ ^^^^^^^^^
    2 │ 
  
  ℹ All headings on a page should have content that is accessible to screen readers.

1
<h1 aria-hidden="true">invisible content</h1>

code-block.html:1:1 lint/a11y/useHeadingContent ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide screen reader accessible content when using heading elements.
  
  > 1 │ <h1 aria-hidden="true">invisible content</h1>
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ All headings on a page should have content that is accessible to screen readers.

1
<h1><span aria-hidden="true">hidden</span></h1>

code-block.html:1:1 lint/a11y/useHeadingContent ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide screen reader accessible content when using heading elements.
  
  > 1 │ <h1><span aria-hidden="true">hidden</span></h1>
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ All headings on a page should have content that is accessible to screen readers.

Valid

1
<h1>heading</h1>

1
<h1 aria-label="Screen reader content"></h1>

1
<h1><span aria-hidden="true">hidden</span> visible content</h1>

Accessibility guidelines

WCAG 2.4.6