How to Fix Missing Alt Text (WCAG 1.1.1)

Missing alt text is, by a wide margin, the most common WCAG violation we find. It's also one of the easiest to fix — if you know the rules.

This guide covers WCAG Success Criterion 1.1.1 Non-text Content and exactly how to write alt text that passes automated scans and actually helps screen reader users.

The Rule

Every <img> element must have an alt attribute. There are no exceptions. If the image is meaningful, the alt describes it. If the image is decorative, the alt is empty (alt="").

<!-- Meaningful image: describe it -->
<img src="ceo.jpg" alt="Jane Smith, CEO of Acme Corporation, smiling">

<!-- Decorative image: empty alt -->
<img src="divider.svg" alt="">

<!-- WRONG: no alt attribute at all -->
<img src="logo.png">

The last example fails WCAG. Screen readers will announce the file name ("logo dot png"), which is useless.

When to Use Empty Alt

An empty alt="" (not the same as no alt attribute) tells screen readers to skip the image entirely. Use it when:

• The image is purely decorative (a dividing line, a background flourish)
• The image duplicates nearby text content (a logo next to the company name in text)
• The image is a spacer or layout element

<!-- The company name is already in text — skip the logo image -->
<a href="/">
  <img src="logo.svg" alt="">
  Acme Corporation
</a>

How to Write Good Alt Text

Describe the function, not the appearance. If an image is a link or button, the alt text should describe where the link goes or what the button does — not what the image looks like.

<!-- Bad: describes the photo -->
<a href="/about">
  <img src="team.jpg" alt="Group of people in an office">
</a>

<!-- Good: describes the link destination -->
<a href="/about">
  <img src="team.jpg" alt="About our team">
</a>

Don't start with "image of" or "picture of". Screen readers already announce that it's an image. "Image of a dog" becomes "image, image of a dog". Just write "a golden retriever puppy sitting on grass".

Be concise. Alt text should typically be under 125 characters. If you need more, put the detail in the surrounding text or a proper caption.

Include text that appears in the image. If an image contains readable text (a sign, a poster, a quote graphic), the alt must include that text verbatim.

<img src="sale-banner.png" alt="20% off all outerwear this weekend">

Special Cases

Product images

For e-commerce, alt text should identify the product and any variant details visible in the image.

<img src="wallet-red.jpg" alt="Leather bifold wallet in red, front view">

Icons

Decorative icons next to text labels should have empty alt. Icon-only buttons need meaningful alt text or an aria-label.

<!-- Icon with visible text: empty alt -->
<button><img src="cart.svg" alt=""> Cart (3)</button>

<!-- Icon alone: meaningful alt -->
<button><img src="cart.svg" alt="View cart, 3 items"></button>

<!-- Or, better, use aria-label on the button -->
<button aria-label="View cart, 3 items"><img src="cart.svg" alt=""></button>

Charts and infographics

Complex images need a short alt and a longer description nearby or linked.

<img src="revenue-chart.png" alt="Bar chart of quarterly revenue from 2020 to 2024. Full data below.">
<details>
  <summary>Chart data</summary>
  <table>...</table>
</details>

CSS background images

Background images declared in CSS are invisible to screen readers by default. If the image conveys information, move it to an <img> tag with proper alt text. If it's purely decorative, leave it in CSS.

How to Audit Your Site

The fastest way to find all your missing alt text: run a free wcagrepair.com scan. Our scanner uses axe-core, which catches every missing alt attribute and reports the exact element and page URL.

If you use WordPress or Shopify, your admin has alt text fields for every uploaded image — you just need to fill them in. For custom sites, our $29 remediation guide tells you exactly which images need alt text and suggests values based on context.

Summary

1. Every <img> must have an alt attribute — no exceptions.
2. Empty alt="" is correct for decorative images.
3. Describe function over appearance, especially for linked images.
4. Skip "image of" and "picture of".
5. Include any text visible in the image.
6. Keep it under 125 characters when possible.

Fix your alt text and you've eliminated the single largest category of accessibility violations on your site.