Alt-Text Auditor — Find Missing & Bad Alts in HTML

Alt text is for people who cannot see the image

Screen readers announce images and read their alt text aloud. Where a meaningful image has no alt attribute at all, many will fall back to reading the file name — so a decorative graphic called hero-bg-final-v2.jpg gets spelled out to someone who only wanted the article. That, and not a ranking loss, is what an alt audit is actually preventing.

Search engines do read alt text, and it genuinely helps them place an image in image search. But the two audiences do not need different text. Writing for a person who cannot see the image satisfies the search engine automatically; writing for the search engine produces keyword-stuffed alt that helps nobody and is read aloud, word for word, to a real listener.

An empty alt is a correct answer, not an omission

This is the distinction worth taking away, and the auditor reports the two cases separately for exactly that reason.

<img src="flourish.png" alt=""> says: this image carries no information, skip it. That is the right markup for a spacer, a background texture, or an icon that only repeats the label beside it.

<img src="flourish.png"> says nothing at all, and leaves the screen reader to improvise — usually with the file name.

So an empty alt is a decision and a missing alt is an oversight, even though they look almost identical in the markup. The auditor counts empty alts under "decorative" rather than flagging them, and it does flag the missing ones. A bare <img> with no attributes whatsoever is caught too.

Writing one that works

Describe what the image shows and what it is doing on this page. The same photograph needs different alt text in different articles: a market stall might be "stall piled with ripe tomatoes" in a recipe and "smallholder produce at a district market" in a piece on farm income. Neither is more correct in the abstract — the page decides.

Do not open with "image of" or "photo of". The screen reader has already said it is an image, so those words are pure repetition. Start with the subject.

For a chart, describe the finding rather than the geometry. "Revenue grew in every region across the four quarters" is useful; reading out each bar in turn is not, and if the underlying numbers matter they belong in a table or in the text where everyone can reach them.

The two length flags are heuristics

Over 125 characters is reported as too long. The number reflects a real constraint — some assistive technology truncates around there — so an over-long alt risks being cut mid-sentence. The fix is usually not compression: a description that genuinely needs 300 characters wants a caption or a paragraph next to the image, with the alt carrying the short version.

Under 10 characters is reported as too short, and this one is a nudge rather than a fault. "ACME logo" is nine characters and completely correct. Read that flag as check this one, never as this is broken — a tool counting characters cannot tell a terse-but-right description from a lazy one.

What it reads, and what it cannot judge

Paste HTML and you get a row per image with its src, colour-coded by status, plus six totals: images found, missing alt, too long, too short, good, and decorative. It parses the markup you paste — it does not fetch a URL or crawl a site — and everything runs in your browser.

Two limits worth knowing. It reads alt and src only when the values are quoted, so an unquoted attribute will be reported as missing when it is merely written unconventionally. And it cannot tell whether your description is accurate, or whether it matches the image and the surrounding text. Structure is checkable; meaning is not, and that part stays with you.

To work on the images themselves rather than their descriptions — re-encoding to a smaller format, resizing, comparing file sizes — use the image optimizer.