# Image elements do not have [alt] attributes: what it means and how to fix it

**Audit ID:** `image-alt` · **Category:** Accessibility

Every meaningful `<img>` needs an `alt` attribute. Screen readers announce alt text; without it, blind users get "image" or the URL filename. This audit also affects SEO, Google uses alt text to understand image content for image search and image-related rankings.

## TL;DR

- **What:** One or more `<img>` elements are missing the `alt` attribute.
- **Why it matters:** Accessibility, SEO, and graceful degradation when images fail to load.
- **Fix:** Add `alt` to every `<img>`. Use empty `alt=""` for decorative images. Be descriptive for content images.

## What the audit checks

Lighthouse fails the audit when any `<img>` element lacks an `alt` attribute. Note: an empty `alt=""` is *valid*, it marks an image as decorative and tells screen readers to skip it. Missing entirely is the failure.

## Why it matters

### Accessibility

Screen readers handle `<img>` based on the alt attribute:
- **Has alt text:** the text is announced
- **`alt=""`:** the image is skipped (correct for decorative images)
- **No alt attribute:** the screen reader announces "image" or the filename (`hero-banner-final-v3.jpg`), useless and confusing

### SEO

Google Images is the second-largest search engine. Alt text is one of the strongest signals for image search ranking and a useful signal for the overall page topic.

### Graceful degradation

When images fail to load (network errors, blocked by content blockers, slow connections), the browser displays the alt text in the image's place. Without it, users see a broken icon.

## The fix

### Content images: describe what's in the image

```html
<!-- WRONG -->
<img src="/team-photo.jpg" />

<!-- RIGHT -->
<img src="/team-photo.jpg"
     alt="Eight engineers gathered around a whiteboard discussing system architecture" />
```

### Decorative images: use empty alt

If an image adds no information (background patterns, decorative dividers, icons paired with adjacent text), use `alt=""`:

```html
<button>
  <img src="/icons/chevron.svg" alt="" />
  Continue
</button>
```

The "Continue" text already conveys the meaning. The chevron is decorative.

### Images that are links: describe the link destination

```html
<!-- WRONG: vague -->
<a href="/account">
  <img src="/avatar.jpg" alt="Avatar" />
</a>

<!-- RIGHT: alt describes where the link goes -->
<a href="/account">
  <img src="/avatar.jpg" alt="Your account settings" />
</a>
```

### Images with text in them

If an image contains text (a quote graphic, an infographic header), include the text in the alt:

```html
<img src="/quote-card.png"
     alt="Quote from Jane Doe: 'This tool saved us 12 hours per week.'" />
```

For complex infographics, use `alt` for the short version and provide a longer text description nearby or via `aria-describedby`.

## Common mistakes

- **`alt="image"`**, the screen reader already says "image" before announcing the alt. So you get "image, image."
- **`alt="picture of a cat"`**, same issue. Say "Tabby cat napping on a windowsill", not "picture of...".
- **Filename as alt** (`alt="IMG_4521.jpg"`), useless. Common when CMS uploads auto-populate the field.
- **Identical alt text on every image of the same type**, each image needs unique, context-appropriate alt text.
- **Stuffing keywords**, `alt="lighthouse audit lighthouse tool fix lighthouse score"` is spam. Write naturally.
- **Missing alt on background images via CSS**, `background-image: url(...)` doesn't have alt text. If the image is meaningful, put it in HTML with `<img>`, not CSS.

## Writing good alt text

Ask yourself: *if this image disappeared and was replaced with text, what text would convey the same information?*

- **Photos:** describe what's in the photo and why it's relevant
- **Charts/graphs:** state the key insight, not just "bar chart"
- **Icons (when meaningful):** describe the action ("Search", "Close", not "Magnifying glass")
- **Logos:** company name (`alt="Stripe"`, not `"Stripe logo"`)
- **Diagrams:** describe what the diagram shows in plain language

## Framework patterns

### React / Next.js

```jsx
<Image src="/hero.jpg" alt="..." width={1200} height={800} />
```

ESLint rule `jsx-a11y/alt-text` will catch missing alts in CI.

### Vue

Use the official `eslint-plugin-vuejs-accessibility` package.

### WordPress

Set the alt attribute in the Media Library when uploading, it carries through automatically.

## Verification

1. Re-run Lighthouse, `image-alt` audit should pass.
2. Use the axe DevTools extension for a deeper check.
3. Test with VoiceOver or NVDA on a few representative pages.
4. Disable images in your browser (or DevTools → Network → block image requests) to see how the page degrades.

## Related audits

- [Color contrast](/audits/color-contrast), visual accessibility
- [Document does not have a main landmark](/audits/document-main-landmark), page structure
- [Heading order](/audits/heading-order), semantic outline
- [Meta description](/audits/meta-description), SEO

---

Audit your URL at https://lighthouse-md.com.