role-img-alt

Description

The role-img-alt rule ensures that elements with role="img" have an accessible name. The role="img" attribute is used when a non-<img> element, such as an SVG, a group of icons, or a CSS-rendered image, is intended to convey visual information. Without an accessible name, screen reader users receive no information about the visual content, making it completely invisible to them.

This rule meets WCAG requirements by:

1. Providing Text Alternatives (WCAG 1.1.1 Non-text Content): It ensures that all non-text content that conveys information has a text alternative that serves an equivalent purpose, allowing users who cannot see the visual content to receive the same information through assistive technologies.
2. Programmatic Name Determination (WCAG 4.1.2 Name, Role, Value): It ensures that the name of every element used as an image can be programmatically determined by assistive technologies.

To comply with this rule, every element with role="img" must have an accessible name provided via aria-label or aria-labelledby.

Examples

This example shows a <div> with role="img" wrapping an SVG icon but with no accessible name. Screen readers skip this element entirely or announce it without any descriptive information.

Here, aria-label is added to the element with role="img", giving screen reader users a meaningful description of the visual content.

How to fix?

To fix violations of the role-img-alt rule, follow these steps:

• Add an aria-label attribute directly on the element with role="img", with a concise description of what the image conveys.

• Alternatively, use aria-labelledby to reference a visible element on the page that already describes the image, such as a nearby caption or heading.

• If the image is purely decorative and conveys no information, use role="presentation" instead of role="img" to indicate that assistive technologies should ignore it.

• Ensure the accessible name describes the meaningful content or purpose of the image, not just “image” or “icon”, so users receive the same information as sighted users.

Reference

• WCAG Success Criterion 1.1.1: Non-text Content

• WCAG Success Criterion 4.1.2: Name, Role, Value