# Images have alt text

- **Pattern:** `ab-002533` (`site-health-check.accessibility-mobile.image-alt-text`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002533
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002533)

## Why it matters

Screen readers announce images using the `alt` attribute. When `alt` is absent entirely — not empty, but missing — most screen readers announce the image filename or URL instead, producing output like 'img-2847-final-v3.jpg' read aloud to a user who cannot see the image. WCAG 2.2 SC 1.1.1 (Non-text Content) is a Level A requirement that mandates text alternatives for all non-decorative images. Section 508 (2018 refresh) 504.2 applies the same obligation. An empty `alt=""` is correct for decorative images — it signals 'skip this.' The missing-attribute case is distinct and always a failure regardless of intent.

## Severity rationale

Info because missing alt text affects screen reader users specifically, but does not degrade the experience for sighted users — severity reflects targeted impact rather than universal failure.

## Remediation

Add an `alt` attribute to every `<img>` tag. Describe what the image conveys for content images; use an empty string for decorative images:

```html
<!-- Content image — describe the meaningful information -->
<img src="chart.png" alt="Bar chart showing 40% growth in Q3 2024">

<!-- Decorative image — empty alt suppresses screen reader announcement -->
<img src="divider.svg" alt="">

<!-- Icon inside a button — describe the action on the button, not the icon -->
<button aria-label="Close dialog"><img src="x-icon.svg" alt=""></button>
```

In Next.js, the `<Image>` component enforces `alt` at the TypeScript level — the prop is required. For icon libraries (Lucide, Heroicons), use `aria-label` on the containing interactive element and set `aria-hidden="true"` on the icon itself.

## Detection

- **ID:** `image-alt-text`
- **Severity:** `info`
- **What to look for:** Count the total number of `<img>` tags in the HTML. For each `<img>`, check whether an `alt` attribute is present (any value, including empty string `alt=""`). Count the number of images missing the `alt` attribute entirely. Decorative images with `alt=""` (empty alt) are correct and count as having alt text. Images without any `alt` attribute at all are failures.
- **Pass criteria:** 100% of `<img>` tags have an `alt` attribute present (value can be empty string `""` for decorative images). Report: "X of Y images have alt attributes." If all images have alt text, report the count to confirm inspection.
- **Fail criteria:** 1 or more `<img>` tags have no `alt` attribute at all (the attribute is entirely absent, not just empty).
- **Skip (N/A) when:** The page contains 0 `<img>` tags in the HTML (nothing to evaluate).
- **Error when:** SPA detected.
- **Cross-reference:** For comprehensive image accessibility including alt text quality, ARIA roles, and decorative image handling, the Accessibility Fundamentals audit (`accessibility-fundamentals`) covers WCAG compliance in depth.
- **Detail on fail:** `"3 of 7 images are missing alt attributes"`
- **Remediation:** The `alt` attribute provides text alternatives for screen readers and displays when images fail to load. Add descriptive alt text to every content image:

  ```html
  <!-- Content image — describe what it shows -->
  <img src="team.jpg" alt="The founding team at their first hackathon">

  <!-- Decorative image — use empty alt -->
  <img src="divider.svg" alt="">
  ```

  In Next.js, the `<Image>` component requires `alt` by default. For icons used as buttons, use `aria-label` on the button instead of alt on the image.

## External references

- wcag 1.1.1
- section-508 504.2

Taxons: accessibility

HTML version: https://auditbuffet.com/patterns/ab-002533