Alt text: when to write it, when to leave it empty
Alt text is the alt attribute that gives an image a text alternative for screen readers and failed loads. When to describe, when to leave it empty.
Alt text is the text in an image’s alt attribute: what a screen reader announces in place of the image, and what the browser shows when the image does not load.
WCAG 2.2 success criterion 1.1.1, Non-text Content, asks for a text alternative that serves the same purpose as the image. The W3C’s image tutorials split images into two kinds. An informative image gets a short description of what it conveys. A decorative one gets an empty alt="", so assistive technology skips it. Leaving the attribute out is the failure, because some screen readers then read out the file name.
Category: Images
Why it matters
For a person using a screen reader, an image with no alt is often just its file name read aloud, something like IMG_4031.jpg. Redundant alt text wastes their time in a different way. Screen readers already announce “image”, so “image of a chart” says it twice, and alt text that repeats the caption below it is read twice too. Google also reads alt text: its image guidelines say it uses alt text, along with computer vision and the page content, to work out what an image shows.
How squirrelscan checks it
images/alt-text reports a page where any <img> has no alt attribute at all. An empty or whitespace-only alt counts as decorative and passes, and the rule does not judge the quality of the text. a11y/image-redundant-alt does look at the text: it flags alt that matches patterns such as “photo of” or a bare “logo”, alt that matches the file name, and alt that repeats a <figcaption> or the text around the image. Two rules cover elements that are easy to forget. a11y/input-image-alt reports a visible <input type="image"> with no name, which is a submit button with nothing to announce. a11y/object-alt reports a visible <object> with no label and no fallback text between its tags.
| Rule | What it flags | Severity |
|---|---|---|
| Missing alt attribute: what an empty alt means | An image with no alt attribute has no name for a screen reader. An empty alt is the correct way to say decorative, and squirrel accepts it. | warning |
| Redundant alt text: image of, filenames and captions | Screen readers already announce that it is an image, so alt starting with ‘photo of’ wastes the announcement. squirrel checks four ways. | warning |
| input type=image without alt: an unnamed submit button | An image input is a submit button drawn as a picture, and with no alt it announces nothing. squirrel checks every one on the page. | error |
| object elements with no alternative content | An embedded object with no fallback is announced as nothing at all. squirrel checks every object element on the page. | warning |
How to fix it
Describe what the image conveys in its context, and mark decoration as decoration:
<img src="/revenue.png" alt="Revenue by quarter, rising from Q1 to Q4" />
<img src="/divider.svg" alt="" />
<input type="image" src="/icons/search.svg" alt="Search" />Skip “image of” and do not paste the caption into the alt (the redundant alt fix). An icon inside a button that already has a label takes alt="" (the alt attribute fix). An image input is a button, so its alt names the action, never alt="" (the image input fix). Put a link to the resource between an <object>’s tags (the object fix).
Run the check
squirrel audit https://example.com --rule-include images/alt-text,a11y/image-redundant-alt,a11y/input-image-alt,a11y/object-altA signed-out local audit costs nothing.
Related terms
- WCAG: The W3C’s Web Content Accessibility Guidelines, organised as testable success criteria at levels A, AA and AAA; 2.2 is current.
- Accessible name: The name assistive technology announces for an element, computed from its content, label, aria-label or aria-labelledby.
- Responsive images: Serving differently sized image files with srcset, sizes and
<picture>so each device downloads one that fits.