Heading element exists but has no content.
Description
This rule automatically scans every HTML heading element<h1> through <h6> and every element with role="heading" and reports the ones whose content is empty. A heading is flagged when it has no child nodes at all, when it contains only whitespace, or when its nested elements do not contribute any text, so <h1></h1>, <h2> </h2>, and <h3><span></span></h3> are all reported with the message Heading element should not have an empty content.
This check maps to WCAG Success Criterion 2.4.6 Headings and Labels (Level AA) and to the general technique G130: Providing descriptive headings.
Headings are the structural skeleton of a page. They label each section so that users understand what information the Web page contains and how that information is organized. A heading that renders as whitespace, or that is styled with a large font size but carries no text, is a “ghost” heading: sighted users scroll past it believing a section is missing, while assistive technology presents it as a blank entry in the document outline.
Disabilities impacted
- Screen reader users (blind) – Screen readers expose headings in a dedicated list or rotor and jump between them with a single key. An empty heading shows up as a blank item in that list; activating it lands the user on an unlabeled spot, so they cannot tell which topic the section covers or whether they have already visited it.
- Visual impairments – Users operating under magnification rely on headings as visual markers to move across a page. An empty heading provides no structure and no anchor, making long pages harder to scan and easy to get lost in, especially when styling still makes the empty element look like a real heading.
- Cognitive disabilities – People with memory or comprehension difficulties depend on concise, descriptive headings to understand how content is grouped and to decide what to read. A heading with no text forces them to reconstruct the section’s purpose from its body, adds guesswork, and raises cognitive load.
- Motor disabilities – Users who operate a switch, voice control, or a keyboard shortcut bar often navigate by hopping between headings to skip irrelevant content. Every empty heading they land on wastes an activation and pushes them back to line-by-line reading.
Why it matters
Headings are the primary navigation aid for assistive technology users, so a heading that exists but carries no content silently breaks the outline of the document. WCAG summarizes the intent of this criterion as:
The intent of this Success Criterion is to help users understand what information is contained in Web pages and how that information is organized. When headings are clear and descriptive, users can find the information they seek more easily, and they can understand the relationships between different parts of the same content.
Beyond assistive technology users, empty headings degrade the machine-readable outline that browsers and compliance tools rely on, and they complicate conformance with the ADA, the European Accessibility Act (EAA), and Section 508 of the Rehabilitation Act. Fixing an empty heading is usually a one-line change that removes a genuine barrier for every user group that navigates by structure.
Coding problems and solutions
Common coding problems
- Completely empty heading element –
<h1></h1>or<h2></h2>with no children at all, often left behind by CMS editors, component libraries, or find-and-replace refactors. - Whitespace-only content –
<h2> </h2>or markup containing only newlines and tabs that looks styled and correct but contributes zero text to the accessible name. - Nested empty wrappers –
<h3><span class="icon"></span></h3>or<h3><p></p></h3>: the heading has descendant elements, but they carry no readable text, so the rule still flags it. - Comments-only headings –
<h4><!-- badge placeholder --></h4>: HTML comments are not text content and are ignored when the visible name is computed. - Headings populated by JavaScript that never runs – Single-page applications render heading placeholders immediately and fill them after an asynchronous request; if the request fails or the callback is never wired up, the heading stays empty.
- Empty elements with role=”heading” – A
<div role="heading" aria-level="2"></div>that substitutes for a native heading announces nothing when it contains only decorative children.
How to fix it
Add descriptive text content
Give the heading real text that describes the section that follows it. Visible text is announced by every screen reader and doubles as the visual label, so prefer it over hidden alternatives such as aria-label or a title attribute whenever the heading must be visible.
<h1>SiteLint accessibility audit report</h1>
<h2>Checkout steps</h2>
<h3>Payment and shipping</h3><h1></h1>
<h2> </h2>
<h3>
</h3>Remove empty wrappers or fill them with text
Headings frequently end up wrapping an empty icon span, an SVG, or a placeholder element. Remove wrappers that contribute nothing, or place the descriptive text inside the nested element instead of beside it.
<h3><span class="label-icon"></span>Account settings</h3>
<h3><span>Password and security</span></h3><h3><span class="label-icon"></span></h3>
<h3><p></p></h3>
<h3><span></span></h3>
<!-- Every nested element is empty, so each heading
announces no text to assistive technology. -->Populate dynamic headings with a fallback
When a single-page application or CMS renders a heading only after an asynchronous request, always provide a fallback text value so the heading never remains empty, and wrap the request in error handling so failures are visible instead of silent.
<h2 id="page-title"></h2>
<script>
const pageHeading = document.getElementById('page-title');
const renderPageTitle = async () => {
try {
const response = await globalThis.fetch('/api/page');
const page = await response.json();
pageHeading.textContent = page.title || 'Article';
} catch (err) {
console.error('Page title fallback applied', err);
pageHeading.textContent = 'Article';
}
};
renderPageTitle();
</script><h2 id="page-title"></h2>
<script>
const pageHeading = document.getElementById('page-title');
globalThis.fetch('/api/page')
.then((response) => response.json())
.then((page) => {
pageHeading.textContent = page.title;
});
// No fallback and no error handling: if the request fails
// the callback never runs and the heading stays empty.
</script>Give elements with role=”heading” real text
When a <div>, <span>, or other element is given role="heading", it must contain text that describes its section, and aria-level expresses its depth in the outline. Never use an empty element and rely on styling alone to make it look like a heading.
<div role="heading" aria-level="2" class="section-title">
Shipping options
</div><div role="heading" aria-level="2" class="section-title">
<span class="spinner" aria-hidden="true"></span>
</div>
<!-- The heading announces nothing: its only child is a
decorative spinner with no accessible text. -->Known Limitations
- Shadow DOM – Headings rendered inside shadow roots (custom elements, encapsulated component libraries) are not traversed by the rule’s selector, which operates on the light DOM. Headings inside Web Components must be audited separately.
- Frames and iframes – Pages composed with
<iframe>or<frame>embed documents whose headings are invisible to this rule. Each embedded document must be audited against this criterion independently. - Single-page applications (SPAs) and dynamic content – The rule evaluates the DOM at scan time. Headings that are rendered after an asynchronous request, lazy-loaded on scroll, or mounted after user interaction may not exist yet and will not be reported.
- CSS-generated text – A heading that is filled only by
::beforeor::afterpseudo-element content is reported as empty, because the rule reads DOM text nodes rather than computed styles, even though the element may show text visually. - aria-hidden context – A heading nested inside a container with
aria-hidden="true"can still be reported as empty even though its content is intentionally hidden from assistive technology, depending on how that context is treated during the scan. - Intent not detectable – The rule cannot judge whether an empty heading is a deliberate placeholder inside a loading flow or an unfinished section, so results should be reviewed in context rather than fixed blindly.
Resources
- WCAG 2.2 Success Criterion 2.4.6 Headings and Labels – W3C
- Understanding SC 2.4.6 Headings and Labels – W3C WAI
- Technique G130: Providing descriptive headings – W3C WAI
- The HTML section heading elements – MDN Web Docs
- ARIA heading role – MDN Web Docs
Rule
- Audit: accessibility
- Standard: WCAG
- Level: AA
- Success Criteria: 2.4.6
- Rule ID:
empty_heading