The role-img-alt rule flags elements with role="img" – a <div>, a <span>, an icon – that have no accessible name. The role tells assistive technology "this is one image", and then there is nothing to announce. The fix is an aria-label or aria-labelledby that says what the image means, or, if it is decoration, removing the role and hiding it.
What the rule means
role="img" turns any element into a single graphic in the accessibility tree. Its content no longer counts: the stars, the emoji or the icon-font glyph inside become part of the picture, and assistive technology reads only the name the author gives it. With no name, a screen reader says "image" or skips it.
axe accepts aria-label, aria-labelledby or a title attribute as the name. Text inside the element does not count, because an image does not take its name from its content. Elements hidden with aria-hidden="true" are not checked.
The rule finds a missing name. It cannot tell whether "Rated 4 out of 5" is actually the rating shown, or whether the element needed role="img" at all – that is a human judgement.
Who is affected
Blind and partially sighted people using a screen reader, who hear "image" – or nothing – where sighted visitors see a rating, a status icon or a hero picture. Braille display users get the same empty cell. The information is lost at exactly the point where the page relies on it, for example a product's star rating or a "sold out" badge drawn as an icon.
Why the check fails
- Star ratings built from icon fonts or Unicode stars, wrapped in
role="img"so screen readers do not read "star star star" – and then never named. - CSS background images on a
<div role="img">for hero banners and team photos, where the role was added but no label. - Emoji wrapped in
<span role="img">– a pattern from React linting guidance – without thearia-labelthat goes with it. - Icon-font icons (
<i class="icon icon-truck" role="img">) in feature lists and status badges. - Component libraries that set the role by default and leave the label as an optional prop nobody fills.
How to fix it
- Decide whether the image carries information. If it does, give it an
aria-labelwith that information – the rating, the status, what the picture shows. - If a visible caption already says it, point to that text with
aria-labelledbyinstead of repeating it. - If it is decoration, remove
role="img"and addaria-hidden="true"so assistive technology ignores it.
<!-- Before: role="img" with no name – the rating is lost -->
<div class="rating" role="img">
<span aria-hidden="true">★★★★☆</span>
</div>
<!-- Before: a background image made an "image", but unnamed -->
<div class="hero__image" role="img"></div><!-- After: the name says what the stars mean -->
<div class="rating" role="img" aria-label="Rated 4 out of 5">
<span aria-hidden="true">★★★★☆</span>
</div>
<!-- After: the hero picture is named by its visible caption -->
<div class="hero__image" role="img" aria-labelledby="hero-caption"></div>
<p id="hero-caption">Our workshop in Leipzig, spring 2026</p>A purely decorative icon needs neither a role nor a name:
<i class="icon icon-sparkle" aria-hidden="true"></i>How to test it manually
- Search the page source or the Elements panel for
role="img". - Select each element and open the Accessibility pane in developer tools (Chrome, Edge) or Firefox's accessibility inspector. Check the "Name" row.
- Compare the name with what you see: does it say what the graphic tells a sighted visitor? A star rating should read as a number, not as "stars".
- Listen with a screen reader (NVDA or VoiceOver). Decorative icons should be silent; informative ones should be announced once, with their meaning.
Related WCAG criterion
1.1.1 Non-text Content, Level A. Related: 1.3.1 Info and Relationships when the graphic stands in for structured information such as a rating, and 4.1.2 Name, Role, Value for the general rule that a role needs a name.
How Reviseberg reports it
Reviseberg runs role-img-alt on every crawled page at 1280px. The issue list shows the rule with its severity, WCAG criterion and level, the number of elements and pages affected, and the points you get back by fixing it. Ratings and badges usually come from one component, so a single fix often clears hundreds of occurrences; the detail view gives the CSS selector, the HTML snippet and every affected page.
You can mark a finding as "ignore", "can't fix" or "false positive" with a reason; every decision is logged. A clean result never marks 1.1.1 as passed on its own: whether each name is right is for a person to confirm.