Accessibility Rule: Images must have alternative text

About This Accessibility Rule

Images are a fundamental part of web content, but they are inherently visual. Screen readers cannot interpret the pixels of an image — they rely entirely on a text alternative to describe the image’s content and purpose to the user. Without alternative text, a screen reader may read out the image’s file name (e.g., “IMG_20230415_093012.jpg”), which is meaningless and confusing. In the worst case, the image is silently skipped, and the user misses critical information.

This rule primarily affects people who are blind or deafblind, who depend on screen readers or braille displays to access content. Users with low vision who rely on text magnification or high-contrast modes can also benefit from well-written alternative text.

Why This Matters

This rule maps to WCAG 2.2 Success Criterion 1.1.1: Non-text Content (Level A), which requires that all non-text content presented to the user has a text alternative that serves an equivalent purpose. It is also required by Section 508 and EN 301 549. Because it is a Level A requirement, it represents the absolute minimum baseline for accessibility — failing it means your content is fundamentally inaccessible to many users.

How to Provide Alternative Text

There are three main techniques for giving an image accessible alternative text:

The alt attribute — the most common and preferred method for <img> elements.
The aria-label attribute — provides an accessible name directly on the element.
The aria-labelledby attribute — points to the id of another element that contains the descriptive text.

Writing Good Alt Text

When writing alternative text, consider these questions:

Why is this image here? What role does it play in the content?
What information does it convey? What would a sighted user take away from it?
If you removed the image, what words would replace it to preserve the same meaning?

Keep alt text concise and descriptive. Avoid phrases like “image of” or “picture of” — screen readers already announce the element as an image. Don’t use the file name as alt text. Focus on the image’s purpose and meaning, not a pixel-by-pixel description.

Handling Decorative Images

Not every image carries meaning. Decorative images — such as visual separators, background flourishes, or images whose content is fully described in surrounding text — should be hidden from assistive technology. To do this, use an empty alt attribute: alt="".

Do not omit the alt attribute entirely. If alt is missing, screen readers will often fall back to reading the file name, which creates a worse experience than having no announcement at all. An empty alt="" explicitly tells the screen reader to skip the image.

You can also use role="presentation" or role="none" to mark an image as decorative, but an empty alt attribute is simpler and more widely supported.

Examples

Incorrect: Missing Alt Text

The alt attribute is completely absent. A screen reader may announce the file name instead.

<img src="team-photo.jpg">

Incorrect: Unhelpful Alt Text

The alt text contains the file name rather than a meaningful description.

<img src="chart-q3.png" alt="chart-q3.png">

Correct: Descriptive Alt Text Using the `alt` Attribute

<img src="team-photo.jpg" alt="The engineering team gathered around a whiteboard during a planning session">

Correct: Alt Text Using `aria-label`

<img src="revenue-chart.png" aria-label="Bar chart showing quarterly revenue increasing from $2M in Q1 to $3.5M in Q4">

Correct: Alt Text Using `aria-labelledby`

<p id="chart-desc">Bar chart showing quarterly revenue growth from Q1 to Q4 2024.</p>
<img src="revenue-chart.png" aria-labelledby="chart-desc">

Correct: Decorative Image with Empty Alt

This separator line serves no informational purpose and should be hidden from screen readers.

<img src="decorative-line.svg" alt="">

Correct: Decorative Image Using `role="presentation"`

<img src="decorative-swirl.png" role="presentation">

What This Rule Checks

This axe-core rule (image-alt) inspects every <img> element on the page and verifies that it has an accessible text alternative. Specifically, it checks that each <img> has at least one of the following:

A non-empty alt attribute
An aria-label attribute
An aria-labelledby attribute that references a valid element
An empty alt="" (or role="presentation" / role="none") to indicate the image is decorative

If none of these conditions are met, the rule flags the image as a critical accessibility violation.

Learn more: