Skip to main content

Alt Text Audit

What it does

The Alt Text Audit parses pasted HTML, lists every <img> element on the page, and classifies each one’s alt attribute by status: missing entirely, empty (decorative), spammy or generic, too short, too long, or good. The output is a sortable table you can scan in seconds, with summary counts per status so the scale of the problem is visible immediately. It sits in our SEO tool suite alongside the other page-level checkers.

Common situations

You are running an accessibility audit on a content site and need to know which pages have missing alt text. Alt-text gaps are the most common WCAG violation by volume. Paste each page’s HTML, sort by status, identify the missing-alt rows. That is faster than running every page through a full Lighthouse audit when you only need the alt data.

A new template has launched and you suspect images are losing their alt attributes during the migration. Paste a representative page, see whether the previously-tagged images are now missing alts. Template-level breakage is invisible to the eye and shipping in production until someone audits it.

You are checking content the editorial team has produced for whether they are using alt text correctly. Common issues: lots of alt="image" placeholders the WYSIWYG inserted, alt text duplicated from the filename (“DSC_0042.jpg”), oversized alt attributes (whole sentences when a phrase would do).

A complaint has come in that the site is hard to use with a screen reader, but you don’t have time to install a screen reader and walk through the whole content set. The alt audit covers the single biggest accessibility issue, alt text gaps, for any individual page in seconds.

You are reviewing a competitor’s editorial standards to understand whether their alt text discipline is real or aspirational. Compare their stated commitment to accessibility (usually in their footer or about-us page) with what the alt audit shows on their actual content.

What you need to know

Alt text serves three distinct purposes that are often conflated. Accessibility: screen-reader users hear the alt text in place of the image; without it, they hear the filename or nothing at all. SEO: image search uses alt text as one of the primary signals for what an image depicts. Loading: when an image fails to load (broken URL, slow connection), the alt text appears in its place.

The accessibility rules are clear:

  • Decorative images (purely visual, carrying no information) should have empty alt="". This tells screen readers to skip them, which is the right behaviour for decoration.
  • Informative images (carrying content meaning) need descriptive alt text. The description should tell a screen-reader user what the image conveys, in the context of the surrounding content.
  • Functional images (icons inside buttons, logos that link home) need alt text describing the function, not the appearance: alt="Search" not alt="Magnifying glass icon".

The auditor flags six statuses:

  • Missing: no alt attribute at all (<img src="...">). High severity, since screen readers fall back to the filename.
  • Decorative (alt=""): correct for purely visual images. Not flagged as an issue.
  • Spammy/generic: alts like “image”, “photo”, “picture”, “untitled”, “DSC_0042”. Functionally equivalent to missing, because they convey nothing.
  • Short: under 4 characters. Usually a placeholder (“img”, “pic”) or accidentally truncated.
  • Long: over 250 characters. Alt text is meant to be a description, not a paragraph. Long alts indicate the image is being treated as content rather than illustration.
  • Good: descriptive, sensible length, not a generic placeholder.

The right length for alt text is usually 50-150 characters. Below 50 risks under-describing; above 150 starts reading as transcription rather than description. The audit flags only the extremes.

What the audit does not check: whether the alt text is actually accurate. An image of a cat with alt="A dog playing fetch" reads as “good” by length and content shape, and only a human can know it is wrong. The audit is a structural check, not a semantic one.

Frequently asked questions

Should every image have alt text?

Yes. Every <img> should have an alt attribute. The attribute can be empty (alt="") for purely decorative images, but the attribute itself should always be present. Missing the attribute entirely is a WCAG violation; setting it to empty is not.

What’s the difference between alt="" and missing alt?

Empty alt (alt="") tells screen readers “this image has no content meaning, skip it”, which is correct for decoration. Missing alt (no attribute) makes screen readers fall back to filename or descriptive text generation, which is unreliable. Always include the attribute; set it to empty when appropriate.

How long should alt text be?

50 to 150 characters as a guideline. Long enough to convey what the image shows; short enough that screen-reader users don’t get bogged down in description. Avoid full-sentence alts unless the image is genuinely complex (a chart, a diagram).

Is alt text a ranking signal?

Yes for image search. Google uses alt text as a primary signal for what images depict. For regular web search, alt text contributes weakly to the page’s overall keyword profile. Don’t stuff keywords into alt text for SEO; describe the image accurately and the SEO benefit follows.

Should I include the word “image” or “photo” in alt text?

No. Screen readers already announce that the element is an image. “Photo of a cat” is redundant; “A cat sleeping on a windowsill” is the alt. The exception is when the medium is genuinely the point (“Black and white photograph” for an image where the photographic style matters).

What about icons and logos?

Icons inside buttons or links need alt text describing the function (“Search”, “Open menu”, “Submit form”). Logos that link to the homepage can use the brand name as alt (“Acme Corp”). Decorative icons that aren’t functional should use alt="".

Is the audit accurate for dynamic / lazy-loaded images?

The audit reads the HTML you paste in. If the page lazy-loads images via JavaScript and the source HTML doesn’t contain those <img> elements, the audit doesn’t see them. View the rendered DOM (Inspect, then “Edit as HTML” or copy the body’s outer HTML) to capture lazy-loaded images for auditing.

Can I have the same alt text on multiple images?

Yes if they’re truly the same: repeated icons, repeated decorative elements. But if the same alt appears on what should be distinct images, the alts are probably wrong. The audit doesn’t flag duplicates; eyeball the table and look for repetitive entries.

Common problems

Problem: Page has clearly visible images but the audit reports zero <img> tags.

The page is using CSS background-image for those visuals instead of <img> tags. Background images are not screen-reader accessible and have no alt mechanism. The fix is to use <img> tags with proper alt text where the image carries content meaning, or accept the trade-off if the image is purely decorative.

Problem: WordPress media library images all have generic alt text.

WordPress sets the alt to the file’s caption (or the filename if no caption) when the image is inserted. If editors don’t customise the alt, the result is mediocre placeholders. Train the team to fill in alt text on insert; some plugins enforce alt at upload time.

Problem: Audit says the alt is “spammy” but it’s the actual product name.

Product names like “DSC-WX350” or “iPhone 15 Pro Max” can match the spammy pattern (looks like a filename). Verify by reading. If the alt is the genuine product name, ignore the warning. The pattern matching is heuristic; humans always have final say.

Problem: Hero images load via JavaScript and are missing from the audit.

Lazy-loaded or JS-injected images are not in the source HTML the audit parses. Take a snapshot of the rendered DOM (after JavaScript has run) by copying outerHTML in DevTools, then paste that. The audit then sees what users actually see.

Problem: Alt text passes the audit but Lighthouse still flags accessibility issues.

Lighthouse runs more checks than just alt: colour contrast, keyboard navigation, ARIA usage, focus management. Alt is one piece. Use the audit for fast alt-specific checks; use Lighthouse for the full accessibility surface.

Tips

  • Decorative images get alt="". Don’t make screen readers wade through descriptions of background flourishes.
  • Functional images (icons in buttons, logos as links) get alt text describing what they do, not what they look like.
  • Long alt text (over 200 chars) usually means the image is conveying content that should also be in surrounding text. Describe the image briefly, put the detail in body content.
  • Audit on publish, not on schedule. The cost of fixing alt at publish time is one minute per image; the cost of fixing months later is auditing the whole content set.
  • Templates that auto-generate alt text from captions or filenames are worse than leaving it empty. They produce confident-looking but wrong alts that humans never look at again.

Related tools in this suite

The Heading Outline Checker is the natural pair: alts and headings are the two most common accessibility issues, and a page with both clean is dramatically better for screen-reader users. The Page SEO Audit reports alt-missing image counts as part of the overall page report.

What this looks like at scale

For a small site, hand-auditing important pages is fine. For a content site with thousands of pages and editorial staff producing new content daily, the fix has two parts: enforce alt at publish time (CMS rule) and audit existing content periodically. The WP Beacon Plugin crawls every page and reports missing or generic alt text across the whole site.

Take it further

If alt text issues are systemic across a site you have inherited, a one-off audit pass plus a CMS-level enforcement rule is the right scope. Talk through the engagement, and the size of the content set affects how the work is shaped.