Elements with role='img' must have an accessible name.

When an HTML element has role="img", it tells assistive technologies to treat that element as an image. But unlike a native <img> tag, elements like <div>, <span>, or <i> don't have built-in mechanisms (such as the alt attribute) for providing a text alternative. If no accessible name is supplied through aria-label or aria-labelledby, screen readers will announce the element as an image with no description. The user knows something is there but has no idea what it conveys.

This pattern is common when icon fonts, inline SVGs, or CSS background images are wrapped in a container element with role="img". Developers often add the role correctly but forget the corresponding text alternative.

Who is affected

Screen reader users are the primary group affected. When an element with role="img" lacks an accessible name, screen readers typically announce "image" or "graphic" with no further context. The user cannot determine whether the image is a logo, a status icon, an illustration, or something else entirely. This creates a gap in understanding that sighted users don't experience.

Relevant WCAG success criteria

This rule maps to WCAG 2 Success Criterion 1.1.1: Non-text Content (Level A). SC 1.1.1 requires that all non-text content presented to the user has a text alternative that serves an equivalent purpose. Because role="img" explicitly marks an element as non-text content, the element must have an accessible name or be marked as decorative.

How to fix it

The fix depends on whether the image carries meaning or is purely decorative.

Meaningful images

If the image conveys information, add an accessible name using one of these approaches:

• Add an aria-label attribute with a short, descriptive text alternative directly on the element that has role="img".
• Add an aria-labelledby attribute that points to the id of another element whose text content describes the image.

The text alternative should communicate the same information a sighted user would get from the image. Keep it concise but specific. For example, "Company logo" is better than "image" or "logo", and "Warning: action cannot be undone" is better than "icon".

Decorative images

If the image is purely decorative and adds no information, remove role="img" and replace it with role="presentation" or role="none". This tells assistive technologies to ignore the element entirely.

Examples

Missing accessible name (incorrect)

This <div> uses role="img" to present a CSS background image, but it has no accessible name. A screen reader will announce it as an unlabeled image.

<div role="img" style="background-image: url('logo.png'); width: 100px; height: 50px;">
</div>

Using aria-label to provide an accessible name (correct)

Adding aria-label gives screen readers a text alternative to announce.

<div
  role="img"
  aria-label="Acme Corp logo"
  style="background-image: url('logo.png'); width: 100px; height: 50px;">
</div>

Using aria-labelledby to provide an accessible name (correct)

When a visible text element already describes the image, point to it with aria-labelledby.

<span id="chart-label">Quarterly revenue by region</span>
<div role="img" aria-labelledby="chart-label" class="chart-image">
</div>

Icon font with role="img" but no name (incorrect)

Icon fonts are a common case. The <i> element here is announced as an image with no description.

<i class="icon-warning" role="img"></i>

Icon font with an accessible name (correct)

<i class="icon-warning" role="img" aria-label="Warning"></i>

Decorative image using role="presentation" (correct)

If the image is decorative, use role="presentation" or role="none" instead of role="img". No accessible name is needed because assistive technologies will skip the element.

<div
  role="presentation"
  style="background-image: url('decorative-border.png'); height: 10px;">
</div>

Inline SVG with role="img" (correct)

When an inline SVG is given role="img", an aria-label on the SVG element itself provides the accessible name.

<svg role="img" aria-label="Checkmark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
  <path d="M9 16.2L4.8 12l-1.4 1.4L9 19 21 7l-1.4-1.4z"/>
</svg>

Learn more:

W3C Reference

Understanding Non-text Content (WCAG 2.1)

→

MDN Reference

ARIA: img role

→

W3C Reference

Using the aria-label attribute

→