> ## Documentation Index
> Fetch the complete documentation index at: https://docs.37audits.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Image Alt
> Finds images that are missing an alt attribute or carry an empty one, so screen readers and search engines can describe them.
**Accessibility Auditor** — checks that every `` on the audited page carries an `alt` attribute, as required by WCAG 2.2 Success Criterion 1.1.1 (Non-text Content).
Screen readers read the `alt` text aloud, so visitors who cannot see an image still get its message.
Follows WCAG 2.2 Success Criterion 1.1.1 Non-text Content (W3C Recommendation, 12 December 2024).
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 `` element in document order. The page is not rendered, so images added by JavaScript are not seen.
3. **Rules** — each `` with no `alt` attribute is one `FAIL` finding (`400`); each `` 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](https://www.w3.org/TR/WCAG22/#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.
| CheckCode | Status | When it fires | Recommendation | Why it matters |
| - | - | - | - | - |
| `37A-ImageAltAuditor-100` | `INFORMATION` | Always. Records the specification version this auditor implements. | — (recommendation is `null`; nothing for the site to change) | — |
| `37A-ImageAltAuditor-400` | `FAIL` | One finding per `` that has no `alt` attribute at all. | Add an alt attribute to Image "`{src}`" that describes what it shows, or alt="" if it is purely decorative. | Without an alt attribute, screen readers announce the file name or nothing at all, so visitors who cannot see the image lose its message and search engines cannot index it; the page also fails a basic WCAG requirement that accessibility laws reference. |
| `37A-ImageAltAuditor-300` | `WARNING` | One finding per `` whose `alt` attribute is present but empty or whitespace-only. | If Image "`{src}`" conveys information, describe it in its alt attribute; keep alt="" only when the image is purely decorative. | Screen readers skip an image with an empty alt, so if it carries meaning, blind and low-vision visitors miss it and search engines have nothing to index for it. |
| `37A-ImageAltAuditor-200` | `SUCCESS` | All rules passed: the page has no ``, or all `{totalImages}` images have a non-empty `alt`. Message reports the count. | — | — |
| `37A-ImageAltAuditor-500` | `ERROR` | The page could not be fetched (timeout, DNS, TLS, or a non-2xx answer other than a block). | Make sure `{url}` answers with HTTP 2xx, then run the audit again. Last error: `{error}`. | — |
| `37A-ImageAltAuditor-590` | `ERROR` | The audited page answered HTTP 403, HTTP 429 or a Cloudflare challenge, so 37AuditsBot was blocked before it could read the page. | Allow 37AuditsBot in your firewall or bot protection: allowlist its user agent, or verify its Web Bot Auth signature. See [https://www.37audits.com/bot](https://www.37audits.com/bot). | While 37AuditsBot is blocked this audit cannot look at the site, so problems on it go unreported. |
## Output documentation
| Status | Description | Test logic |
| - | - | - |
| **SUCCESS** | Every image has a text alternative | No `` on the page, or every `` has a non-empty `alt` (`200`). |
| **WARNING** | Some images have an empty `alt` | At least one `` has `alt=""` (or whitespace only) and none is missing `alt` (`300`, one check per image). |
| **FAIL** | Some images have no `alt` attribute | At least one `` has no `alt` attribute (`400`, one check per image); empty-alt warnings (`300`) are listed alongside. |
| **ERROR** | The auditor could not read the page | Fetch failure or non-2xx answer (`500`); site blocked 37AuditsBot (`590`). |
| **INFORMATION** | Specification pin | Always emitted (`100`); does not change overall status. |
## 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, `