Filename Alt Text Audit

Content management systems and upload widgets often fill in an image’s alt text with its filename, and authors sometimes type “image” just to get past a required field. Both pass any check that only asks whether alt text exists, but a screen reader user hears “IMG underscore 4032 dot jpg” and learns nothing about the image. WCAG 1.1.1 Non-text Content documents this as failure F30: text alternatives that are not alternatives, such as filenames or placeholder text.

Turning it on

This audit is experimental: it is off by default while we validate it against more real-world sites. To enable it, open a site’s Settings, and switch on Include experimental audits under Scan settings. The setting is per-site, and applies to every scheduled and manual scan of that site from the moment you save it.

How the audit works

The audit reads every rendered image with alt text, including <input type="image">. When an image has an aria-label, that is checked in place of alt. Images with no alt text, or with alt="", are left to the existing image alt text audit.

Each image’s own sources are its src, every srcset candidate, and the srcset candidates of any <source> elements in its <picture>. The audit then compares the alt text against those filenames and a set of common patterns:

• Filename: the alt text is exactly the filename of one of the image’s own sources, such as IMG_4032.jpg. This is reported as a violation.
• Near match: the alt text matches a filename once the extension is dropped, or once dashes and underscores are read as spaces.
• Camera file name: the alt text is a camera, phone or screenshot file name, such as DSC_1234 or Screenshot 2024-01-02 at 10.11.12.
• Looks like a filename: the alt text ends with an image file extension, which happens when a CDN renamed the file but the CMS kept the original name.
• Placeholder text: the whole alt text is a placeholder word such as “image”, “photo” or “logo”, a placeholder word followed by a number, a dimensions string like “300x200”, or only digits or symbols.

Placeholder words are only matched against the whole alt text, so “Photo of the packed tent” is not flagged. Words are checked in English and in the language of the page, for English, Swedish, German, French, Spanish, Italian, Dutch, Norwegian, Danish and Finnish.

Reading the results

Alt text that is exactly one of the image’s own filenames is reported as a violation. Everything else the audit flags is reported as incomplete, because a product code or a short caption can look just like a filename or placeholder. Look at each image and decide whether its alt text describes it.

Flagged images include a screenshot of the image, so you can judge the alt text without leaving A11y Pulse.

You can ignore individual elements you have reviewed and accepted using the same ignore feature you use for other issues.

Limitations

This audit checks that alt text is not a filename or placeholder. It does not check whether alt text that passes is accurate, so a clean result is not a sign that your alt text is good: that still needs human review.

The audit reads alt and aria-label only. Names from aria-labelledby or title, inline SVG, role="img" elements and CSS background images are not checked. Images inside closed shadow roots are not reached. Placeholder words in other languages pass.

Some flagged alt text will be fine. A file named sunset-over-stockholm.jpg with the alt text “Sunset over Stockholm” may describe the image well, and “Logo” may be accurate on a logo design portfolio. These land in incomplete, never in violations.