Accessibility Rule: [role="img"] elements must have an alternative text

About This Accessibility Rule

When you apply role="img" to an element, you’re telling assistive technologies to treat that element as a single image. This is commonly used to group decorative SVG elements, icon fonts, CSS background images, or multiple visual elements into one cohesive image. However, applying the role alone isn’t enough — assistive technologies also need a text alternative that describes the image’s content or purpose.

Without an accessible name, screen readers will either skip the element entirely or announce it as an unlabeled image, leaving users who rely on assistive technology without critical information. This affects screen reader users (who hear content read aloud), braille display users (who read content through tactile output), and to some extent users with low vision who may use screen readers alongside magnification.

This rule relates to WCAG 2.1 Success Criterion 1.1.1 (Non-text Content), which requires that all non-text content presented to the user has a text alternative that serves the equivalent purpose. It is a Level A requirement — the most fundamental level of accessibility compliance.

How to Fix It

Add an accessible name to any element with role="img" using one of these methods:

aria-label: Provide the text alternative directly as an attribute value.
aria-labelledby: Reference the id of another element that contains the descriptive text.
title: Use the title attribute as a fallback (though aria-label and aria-labelledby are preferred, as title has inconsistent support across assistive technologies).

The text alternative should be concise and describe the content or purpose of the image. If the image is purely decorative and conveys no information, use aria-hidden="true" instead of role="img" to hide it from assistive technologies entirely.

Examples

Incorrect: `role="img"` with No Text Alternative

<div role="img">
<!-- SVG icon with no accessible name -->

  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path d="M12 2L2 22h20L12 2z"/>
  </svg>
</div>

A screen reader encounters this as an image but has no name to announce, so the user gets no useful information.

Correct: Using `aria-label`

<div role="img" aria-label="Warning: hazardous area ahead">
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path d="M12 2L2 22h20L12 2z"/>
  </svg>
</div>

Correct: Using `aria-labelledby`

<span id="chart-desc">Quarterly revenue growth from Q1 to Q4 2024</span>
<div role="img" aria-labelledby="chart-desc">
<!-- Complex chart composed of multiple elements -->

  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
    <rect x="10" y="60" width="30" height="40" fill="#4a90d9"/>
    <rect x="50" y="40" width="30" height="60" fill="#4a90d9"/>
    <rect x="90" y="25" width="30" height="75" fill="#4a90d9"/>
    <rect x="130" y="10" width="30" height="90" fill="#4a90d9"/>
  </svg>
</div>

Correct: Using `title`

<div role="img" title="Company logo">
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50">
    <circle cx="25" cy="25" r="20" fill="#333"/>
  </svg>
</div>

Correct: Decorative Image Hidden from Assistive Technology

If the image is purely decorative and adds no meaningful information, hide it instead of labeling it:

<div aria-hidden="true">
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 10">
    <line x1="0" y1="5" x2="100" y2="5" stroke="#ccc" stroke-width="1"/>
  </svg>
</div>