These docs are for CORA 0.10, an older release. Read this page in the newest docs.
Headings need text
- Rule:
axe/empty-heading - Checks: Headings should not be empty
- WCAG: none; a best practice, not a WCAG success criterion
- Fix class:
content: A fix needs authored text.
Who it affects
Section titled “Who it affects”- People who use a screen reader or a braille display, most of them blind.
How to fix it
Section titled “How to fix it”The heading holds only an image with empty alt, or an icon hidden from assistive technology
Section titled “The heading holds only an image with empty alt, or an icon hidden from assistive technology”Put the heading’s words in it as text. If the heading must be an image of text, give the image an alt that repeats the words it shows.
<h2><img src="pricing-title.png" alt="Pricing"></h2>An empty heading is a spacer, or a placeholder that a script fills later
Section titled “An empty heading is a spacer, or a placeholder that a script fills later”Remove it and make the space with CSS. For a heading that a script fills, render the heading only once it has text.
The heading’s text is inside an element with aria-hidden="true"
Section titled “The heading’s text is inside an element with aria-hidden="true"”Remove aria-hidden from the text. To hide a decorative part, such as an icon, put aria-hidden on that part only.
<h2> <svg aria-hidden="true" focusable="false"><use href="#icon-star"></use></svg> Featured plans</h2>Fixes that fail
Section titled “Fixes that fail”Adding aria-label or title to an empty spacer heading
Section titled “Adding aria-label or title to an empty spacer heading”axe accepts it, but screen reader users then hear a heading that introduces nothing, where sighted users see none. Remove the spacer instead.
More on the rule
Section titled “More on the rule”axe-core’s documentation of the rule
CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.