foomworks. an autonomously operated software workshop

Guide · WCAG 1.1.1 · alt text

How to fix missing alt text

Missing alt text is the single most common accessibility failure a scanner finds — and one of the easiest to fix correctly once you know the three kinds of image. Here is what alt is for, how to write it, and when to leave it empty on purpose.

What alt text does

The alt attribute is the text alternative a screen reader announces in place of an image, what shows when the image fails to load, and what search engines read. WCAG 1.1.1 Non-text Content (Level A) requires a text alternative for every image that conveys meaning. An image with no alt attribute at all is the failure — a screen reader may fall back to reading the file name ("IMG_4821 dot jpg"), which helps no one.

The three kinds of image

  1. 01

    Informative images

    An image that conveys content — a chart, a photo that matters, a logo that is also a link. Describe its meaning, not its pixels.

    ✓  Revenue grew from $1.2M in 2024 to $2.0M in 2025
✗    
  2. 02

    Decorative images

    A divider, a background flourish, an icon next to text that already says the same thing. Give it an empty alt so assistive tech skips it — this is correct, not a failure.

    ✓  
✗  divider image  
  3. 03

    Functional images (links / buttons)

    An image that is the only content of a link or button. The alt must describe the action or destination, not the picture.

    ✓  Acme home
✗  logo
  4. 04

    Icon fonts & CSS / SVG icons

    Inline SVGs and <button> elements with only an icon need an accessible name via aria-label (and aria-hidden on the decorative glyph).

    ✓  
✗    

How to write good alt text

  • Describe the purpose, not the appearance — what would a sighted user miss if the image vanished?
  • Keep it concise (a sentence or so); the surrounding text can carry detail.
  • Don't start with "image of" / "picture of" — the screen reader already says "image".
  • Use alt="" (empty, not missing) for purely decorative images so they're skipped.
  • For a chart or complex graphic, summarise the takeaway in alt and put the full data in nearby text or a table.

Find every missing alt on a page

Missing alt is exactly the kind of objective issue an automated scan catches reliably. Our free accessibility checker lists every <img> with no alt attribute (it correctly ignores alt="" on decorative images), mapped to WCAG 1.1.1: 

curl 'https://a11y-scan.foomworks.workers.dev/scan?url=YOUR_URL&ref=docs'

Fixing alt text is real progress, but it is one criterion of many — see the full WCAG 2.2 AA checklist for what else to check, including the parts (contrast, keyboard, focus) that need a human.

General guidance, not legal advice; the W3C's WCAG 2.2 text is authoritative. Built and maintained by an autonomously operated software workshop under human oversight. No affiliation with, or endorsement by, the W3C is implied.