Image Alt

The alt attribute is the text alternative of an image. Screen readers announce it, browsers show it when the image fails to load, and search engines index it. An image with no alt attribute leaves assistive technology guessing (most screen readers fall back to the file name), while alt="" deliberately tells them the image is decorative and can be skipped. This auditor reads the HTML of the audited URL and reports both cases: a missing alt fails, an empty one warns so the owner can confirm the image carries no meaning.

​

How it works

1. Fetch — sends a GET request to the audited URL as 37AuditsBot. A blocked request ends the audit with 590; any other failure (timeout, DNS, TLS, non-2xx answer) ends it with 500.
2. Parse — parses the HTML with jsoup and collects every <img> element in document order. The page is not rendered, so images added by JavaScript are not seen.
3. Rules — each <img> with no alt attribute is one FAIL finding (400); each <img> whose alt is present but empty or whitespace-only is one WARNING finding (300). The finding’s resource is the image’s absolute src (falling back to the raw src, then the page URL), and its data carries src, absoluteSrc, alt and the image’s 1-based index.
4. Aggregate — FAIL wins over WARNING. When every image has a non-empty alt, or the page has no images at all, the audit is SUCCESS (200) with the image count in the message.
5. Specification pin — every run emits 37A-ImageAltAuditor-100 (INFORMATION), naming WCAG 2.2 Success Criterion 1.1.1 Non-text Content (W3C Recommendation of 12 December 2024). It does not change the overall status.

​

What it audits

Every row maps to one checkRule* method and one CheckCode, in the order the auditor runs them. CheckCode suffixes use status ranges: 100 information, 200 success, 300–399 warning, 400–499 fail, 500–599 error.

​

Output documentation

​

Risks and considerations

​

Why alt text matters

• Blind and low-vision visitors rely on screen readers, which can only describe an image through its alt text. A missing alternative hides product photos, charts, buttons drawn as images and infographics from them.
• Search engines index alt text and use it for image search, so descriptive alternatives bring traffic and help rank the page.
• WCAG 1.1.1 is a Level A criterion, the minimum that accessibility laws and procurement rules (ADA, EN 301 549, the European Accessibility Act) point to.

​

Empty alt is not always wrong

• alt="" is the correct markup for a purely decorative image (a spacer, a background flourish, an icon next to its own label). Screen readers skip it on purpose.
• The auditor cannot tell a decorative image from a meaningful one, so an empty alt only warns. Review each warning: keep alt="" for decoration, write a description for anything that carries information.

​

Changes from the previous version of this auditor

• A page whose only problems are empty alt attributes is now WARNING; it used to be FAIL. alt="" is valid for decorative images, so it no longer fails the page on its own.
• The auditor no longer emits a SUCCESS check for every well-described image; a single 200 check with the image count replaces them.
• A fetch failure is reported as ERROR (500) with the observed error instead of a generic message, and a blocked request as 590.

​

What this auditor does not check

• Only the audited URL is parsed; other pages of the site may have images without alt.
• The HTML is not rendered: images inserted by JavaScript, CSS background images, <svg> and <canvas> graphics are not inspected.
• The quality of the alt text is not judged: “image”, “photo” or a file name counts as non-empty. Images with role="presentation" or aria-hidden="true" but no alt still fail, since alt remains required on <img>.