← All rules

Text alternatives

Elements with role="img" need a name

• Rule: role-img-alt
• Severity: Serious
• WCAG level A

Why it matters

role="img" tells assistive technology "this is a picture" and then offers nothing to say about it. A star rating drawn in CSS becomes an announced but empty image.

How to fix it

1. Add aria-label describing what the composition conveys ("Rated 4 out of 5").
2. Use aria-labelledby when the description already exists as visible text.
3. If it is purely decorative, drop role="img" and add aria-hidden="true".

In markup

<div role="img" class="star-rating"></div>

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

The requirement behind it

This rule is one way of failing the following WCAG 2.2 success criteria. The W3C, which writes the standard, explains each of them:

• 1.1.1 Non-text Content (opens in new tab) — WCAG level A

Further reading

Deque University on role-img-alt (opens in new tab)

Deque maintains axe-core, the open-source engine our scanner runs. Their page documents the rule as the engine implements it.

Automated checks find failures a browser can prove. They cannot judge whether a caption is accurate, whether an alt text is useful, or whether a page can be operated end to end with a keyboard — those need a person.