• June 30, 2025

Accessible Text Alternatives for ARIA Images

Rule ID: role-img-alt
Ruleset: axe-core 4.10
User Impact: Serious
Guidelines: WCAG 2.1 (A), WCAG 2.0 (A), WCAG 2.2 (A), Section 508, Trusted Tester, EN 301 549

How to Fix the Problem

When using role="img" on an element to indicate it functions as an image, you must also provide accessible alternative text. This allows assistive technologies, such as screen readers, to convey the purpose or content of the image to users with disabilities. The following techniques are considered accessible and valid:

✅ Correct Examples:

1. Using aria-labelledby:

   html

   KopierenBearbeiten

   <div id="match">Bananas</div>
<div role="img" aria-labelledby="match" id="pass2"></div>


   Here, the second div references the first one via aria-labelledby, creating a text alternative.

2. Referencing a hidden label:

   html

   KopierenBearbeiten

   <div id="hidden-match" style="display:none">Banana bombs</div>
<div role="img" aria-labelledby="hidden-match" id="pass3"></div>


   Hidden labels still provide accessible text.

3. Using aria-label directly:

   html

   KopierenBearbeiten

   <div role="img" aria-label="blah" id="pass1"></div>


   This provides a descriptive label via an attribute.

4. Using the title attribute:

   html

   KopierenBearbeiten

   <div role="img" title="title" id="pass4"></div>


   Though not as robust as aria-label, the title is still read by some assistive technologies.

❌ Incorrect Examples:

These examples lack a usable or valid accessible name:

Key Reminders:

• alt is not valid on elements other than <img>.

• Use aria-label or aria-labelledby for non-<img> elements.

• Make sure all references (like aria-labelledby) point to existing elements with meaningful text.

• Never leave aria-label or title empty if they’re intended to convey alt text.

Why it Matters

People using screen readers cannot see visual content. For them, meaningful text alternatives are the only way to access the information conveyed by images. Without it, they miss out on important context, function, or instructions.

Failing to provide alt text for elements marked as images (role="img") results in silent, inaccessible content — a major usability and compliance issue. Proper text alternatives:

• Enable navigation and comprehension for users who are blind or have low vision

• Help those with cognitive impairments or learning disabilities

• Improve overall accessibility for everyone, including users in text-only environments

Rule Description

This rule ensures that any element using role="img" includes accessible alternative text. That text must meaningfully describe the image or its function, and it must be implemented using valid ARIA attributes (aria-label, aria-labelledby) or the title attribute.

The Algorithm (in simple terms)

1. Find all elements with role="img".

2. Check if they have at least one of the following:

   • A valid, non-empty aria-label

   • A valid aria-labelledby pointing to an element with meaningful text

   • A non-empty title attribute

3. Flag as a failure if none are present.