Custom images need alternative text

• Rule: axe/role-img-alt
• Checks: [role=“img”] and [role=“image”] elements must have alternative text
• WCAG: 1.1.1
• Fix class: content: A fix needs authored text.

Who it affects

• People who use a screen reader or a braille display, most of them blind.

How to fix it

An element shows a CSS background image that conveys information

Name it with aria-label for the information the image gives, decided from its purpose on the page. Better, replace it with an <img> and an alt.

<div class="hero" role="img" aria-label="Volunteers planting trees along the river path"></div>

Several icons or characters together show one value, such as a star rating

Keep role="img" on the element that wraps them and name it for the value they show. Assistive technology ignores the parts inside an image.

<span role="img" aria-label="Rated 4 out of 5">
  <span class="star"></span><span class="star"></span><span class="star"></span><span class="star"></span><span class="star empty"></span>
</span>

The element is decorative, such as an icon beside text that says the same

Remove role="img" and add aria-hidden="true", so assistive technology skips it.

<button type="button"><span class="icon icon-save" aria-hidden="true"></span> Save</button>

Fixes that fail

Adding an alt attribute to a <div> or <span>

alt works only on <img>, <area> and <input type="image">. Elsewhere it is ignored, and the element stays unnamed.

Removing role="img" from an element that conveys information

The rule stops applying, but a CSS background image has no text alternative of its own, so screen reader users lose what it shows.

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.