eslint jsx-a11y heading-has-content empty heading bug

eslint jsx-a11y heading-has-content empty heading bug - how to fix it

TL;DR

Put real content in the heading: text, an aria-label, or a component that renders text. Empty headings used as styling hooks or icon containers fail. One line of why: an empty heading announces as a heading with no name, which breaks heading navigation without conveying anything.

The error, verbatim

/app/src/components/Section.jsx
  6:5  error  Headings must have content and the content must be accessible by a screen reader  jsx-a11y/heading-has-content

Fix it step by step

Step 1: Reproduce on one file

npx eslint src/components/Section.jsx --rule '{"jsx-a11y/heading-has-content": "error"}'

Expected: ESLint prints the heading-has-content error.

Step 2: Find every empty heading

npx eslint src | rg 'heading-has-content' | head -20

Expected: Full list of headings with no accessible content.

Step 3: Inspect each one

rg -n --glob '*.{jsx,tsx}' 'h1' src | head -20

Expected: Shows h1 usages; verify each heading renders text content.

Step 4: Fill the headings and re-lint

npx eslint src | rg -c 'heading-has-content' || echo 0

Expected: Prints 0. Heading navigation now announces a name for every heading.

Step 5: Enforce it in CI

npx eslint src --max-warnings 0 | tail -3

Expected: Clean output; add the lint command to CI with max-warnings 0 so the violation cannot come back.

When to use this skill

• Your linter output names this exact jsx-a11y / a11y rule
• You want the violation fixed at author time so it never reaches axe or CI
• You are adding the rule to a shared eslint config and need the fix pattern

When NOT to use this skill

• The failure comes from axe-core or lighthouse at runtime, not from lint
• You plan to disable the rule project-wide, this skill shows the fix, not the escape hatch

Compatibility

eslint-plugin-jsx-a11y 6.7+ with eslint 8 or 9. The components option lets it see through custom heading components. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

headings must have content accessible by screen reader

The default message, same fix.

jsx-a11y empty h2 error

Practitioner phrasing, usually a styling hook heading.

the rule fires in the editor too

With the eslint extension installed, the same error appears inline while typing; the fix is identical.

Why it happens

Headings get used as styling wrappers or icon containers, ending up with no text content, or they render children that are all aria-hidden icons. The rule requires accessible content: text, or content hidden from sighted users but exposed to screen readers. Dangerously set inner HTML and component children count if they produce text, so the rule is heuristic, but empty-in-source headings almost always fail. Linter rules catch the violation at author time, which is cheaper than any runtime fix. When this rule fires across many files, fix the shared component and mention it in team onboarding so new code does not reintroduce it.

Edge cases

• An icon-only heading needs an aria-label or visually hidden text, the icon alone is not content.
• Headings whose text comes from async data pass lint but fail at runtime until data loads, handle the loading state.
• Configure the components option if your design system wraps headings in custom components.
• After fixing, run the whole lint suite once; a11y rules interact and one fix can surface the next violation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstbIGP1cyEQtKySGY0dPltg