useHeadingContent

JSX and TSX

Summary

• Rule available since: v1.0.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:
  • Same as jsx-a11y/heading-has-content
  • Inspired from @html-eslint/no-empty-headings

How to configure

biome.json

{
  "linter": {
    "rules": {
      "a11y": {
        "useHeadingContent": "error"
      }
    }
  }
}

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 prop.

Examples

Invalid

<h1 />

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

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

<h1><div aria-hidden /></h1>

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

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

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

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

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

<h1></h1>

code-block.jsx: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.
  

Valid

<h1>heading</h1>

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

<h1 aria-label="Screen reader content"><div aria-hidden="true">invisible content</div></h1>

<h1 dangerouslySetInnerHTML={{ __html: "heading" }} />

<h1><div aria-hidden />visible content</h1>

Accessibility guidelines

• WCAG 2.4.6

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code (Edit this Page)
• Test Cases

HTML

Note

This rule has been implemented but not released yet. It will be available in the next release.

Summary

• 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

biome.json

{
  "linter": {
    "rules": {
      "a11y": {
        "useHeadingContent": "error"
      }
    }
  }
}

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.

Note

In .html files, this rule matches element names case-insensitively (e.g., <H1>, <h1>).

In component-based frameworks (Vue, Svelte, Astro), only lowercase element names are checked. PascalCase variants are assumed to be custom components and are ignored.

Examples

Invalid

<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.
  

<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.
  

<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

<h1>heading</h1>

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

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

Accessibility guidelines

• WCAG 2.4.6

Related links

• Disable a rule
• Configure the code fix
• Rule options
• Source Code (Edit this Page)
• Test Cases