Missing alt attribute: what an empty alt means

What the alt attribute is

alt is the text alternative for an image: what a screen reader announces, and what a browser shows when the image does not load. This rule expects one on every <img>. The HTML specification allows a few narrow exceptions, for cases where no alternative text is available and none can be produced, and they do not apply to a normal page.

The two valid states are a description and an empty string. alt="Chart showing revenue by quarter" names an image that carries information. alt="" marks an image as decorative and tells assistive technology to skip it, which is the correct markup for a divider, a background flourish or an icon whose meaning is already in the adjacent text. Omitting the attribute is the failure, because it leaves the software to guess, and most screen readers fall back to reading the filename.

What squirrel checks

The rule runs on every crawled page over the images the parser extracted. It emits a single check named alt-text or alt-text-missing:

• alt-text passes when the page has no images. Message: No images on page, with a value of 0.
• alt-text-missing fails when any image has no alt attribute at all. Message: 3 image(s) missing alt text, listing each image source. Severity warning, weight 5. No further checks run.
• alt-text passes when every image has a non-empty alt. Message: All 12 image(s) have alt text.
• alt-text passes when every image is marked decorative. Message: All 12 image(s) marked decorative (alt="").
• alt-text passes on a mix. Message: 9/12 image(s) have alt text, 3 marked decorative (alt="").

A whitespace-only alt counts as decorative, since it is a sloppy spelling of the same thing. There is no check on the quality or length of the text: this rule only asks whether the attribute is there.

Elements inside <noscript> are skipped: a browser with scripting enabled reads <noscript> content as plain text, so nothing in it loads or renders. See content inside noscript.

How to fix it

<img src="/revenue.png" alt="Revenue by quarter, rising from Q1 to Q4" />
<img src="/divider.svg" alt="" />

Describe what the image conveys in context, not what it depicts in general. Skip “image of” and “photo of”, which screen readers already announce. Keep it under about 125 characters.

For an icon inside a labelled button, the empty alt is right: the button carries the name and the icon should not be announced twice.

Enable / disable

Disable this rule

[rules]
disable = ["images/alt-text"]

Disable all Images rules

[rules]
disable = ["images/*"]

Enable only this rule

[rules]
enable = ["images/alt-text"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• a11y/image-redundant-alt: alt text that repeats the adjacent link or caption.
• links/anchor-text: image-only links whose alt is the link’s name.
• images/figure-figcaption: captions, which are visible text rather than an alternative.
• images/filename-quality: the filename a screen reader falls back to.

Images findings ship in every audit next to the SEO, performance and agent experience rules. See Core Web Vitals for how an agent works through a report.

References

• The img element, MDN
• Decorative images, W3C WAI tutorials
• Google Images best practices

Check your site

Run squirrel audit https://example.com and open the Images section of the report. Every image with no alt attribute is listed by source. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.