[role="img"] elements must have an accessible name

WCAG 1.1.1
Non-text Content

Content available in English only.

Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).

These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.

If you declare role="img", you **must** provide the words to describe it.

Why this matters and how to fix it

Why this matters

Elements with role="img" are treated as images by assistive technologies. If they do not have an accessible name, screen readers announce nothing — users miss important meaning such as brand identity, status, file type, or purpose of controls. This especially affects custom SVG icons and CSS–based images.

How to fix this issue

When using role="img" on a non-<img> element, provide an accessible name using `aria-label` or `aria-labelledby`. If the image is decorative, remove role="img" entirely and use `aria-hidden="true"` instead.

Automated detection · Manual review recommended

Developer guidance

This issue commonly appears in icon components, logo components, and UI frameworks that render SVG inline. Review your design system icon component: require a `label` prop when the icon conveys meaning. Make decorative icons explicitly `aria-hidden="true"` so they do not pollute the accessibility tree.

Code examples

Incorrect Implementation

<div role="img"></div>

Correct Implementation

<div role="img" aria-label="Company logo"></div>

Real-World Examples

Before

<svg role="img"><use href="#icon-download"></use></svg>
<!-- Screen reader announces nothing → user cannot tell what action this represents -->

After

<button>
  <svg role="img" aria-label="Download"></svg>
</button>
<!-- Screen reader: 'Download, button' → clear purpose -->

CSS Example (Guidance)

/* If using background-image for logos, provide a text alternative */
.logo {
  background-image: url('/logo.svg');
}
.logo::after {
  content: "Company logo";
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip: rect(1px, 1px, 1px, 1px);
}

Manual testing

  1. 1. Inspect elements with role="img".
  2. 2. Verify one of the following is present:
  3. • aria-label
  4. • aria-labelledby
  5. • (or confirm image is decorative and remove role="img" + add aria-hidden).
  6. 3. Turn on a screen reader and navigate to the element.
  7. • Expected: The purpose of the image is announced aloud.
  8. 4. If the image conveys meaning in context (e.g., icon-only button), ensure the accessible name expresses that meaning (e.g., 'Settings', 'Delete', 'Download').
eu icon getwcag

Trusted by organizations across Europe working toward WCAG and EAA conformance