Image alt text: what our checker flags and why

What the checker reads

The free audit fetches the page once and parses the HTML as served. No JavaScript runs. It collects every <img> element whose src attribute is not empty, including images inside <picture> and <template>, and skips anything inside <noscript>. For each one it keeps the resolved src URL and the raw alt value. Nothing else about the image is read: not its size, visibility, ARIA attributes or title.

The check

ID: onpage-image-alt-missing · Severity: warning · Scope: the URL you enter
An image is flagged when its alt attribute is absent, or present but empty or whitespace once trimmed. The check fails if at least one image is flagged. The report gives the count and the src of every flagged image, one entry per occurrence, so a logo used in the header and the footer appears twice.

The rule, applied to real markup:

What Google and accessibility guidance say

• Google Search: its image SEO best practices say Google uses alt text "along with computer vision algorithms and the contents of the page" to understand an image, and that alt text is the most important attribute for image metadata. The same page says to avoid "filling alt attributes with keywords", which "may cause your site to be seen as spam", and that alt text on a linked image works as its anchor text.
• What Google can't see: the same guide says "Google doesn't index CSS images", recommends a <title> element for inline <svg>, and asks for a plain src fallback when you use srcset or <picture>. File names give only "very light clues".
• Accessibility: WCAG success criterion 1.1.1 Non-text Content is Level A, the minimum level. It asks for a text alternative for images that carry information, and for decoration to be implemented so assistive technology can ignore it.
• Decorative images: the W3C decorative images tutorial says to use alt="". Leaving the attribute out is worse, because "some screen readers will announce the file name of the image instead". It notes that role="presentation" is "not as widely supported as using a null alt attribute".

What we see on real sites

On 30 October 2026, the latest report for each of the 82 sites checked with this tool showed:

• 45 of 82 fail the alt check. Only two checks fail more often.
• Those 45 pages have 730 flagged images between them. The median is 7 per page and the highest is 121. 10 of the 45 have exactly one.
• 19 of the 45 have the same image flagged more than once, usually a logo or icon repeated in the header, menu and footer. Fixing it in the theme clears every copy.
• 15 of the 45 have at least one flagged .svg file. These are often icons, and many will be decorative.

Our stored results keep only the src of each flagged image, so we can't say how many of those 730 have alt="" and are correct as they are. The snippet below splits the two on your own page. The sample is small, 74 of the 82 pages are homepages, and the people who run the tool are not a random sample of the web. Read the numbers as what our checker finds most often, not as a web-wide rate.

Where our checker and a screen reader can disagree

We read attributes in the served HTML. Screen readers and browsers read the rendered page. In these cases the two can differ:

• Decorative images: alt="" tells a screen reader to skip the image, which is what you want for a divider or a background flourish. We flag it anyway. This is the largest source of warnings you can safely leave alone.
• ARIA: aria-label, aria-labelledby, aria-hidden and role="presentation" or role="none" change what a screen reader announces. We ignore them. Only alt counts.
• Hidden and template images: an image with display:none, the hidden attribute, or inside <template> is counted although nobody sees or hears it.
• Lazy loading: an image whose real URL is only in data-src is not counted. If the plugin puts a data: placeholder in src, it is counted.
• JavaScript: images added after load, such as a slider or a product gallery rendered on the client, are not counted at all.

These are gaps in our checker, documented here rather than left silent. If an alt result surprises you, run the snippet below. Its last lines count each case on your page.

Reproduce what our checker saw

Paste this into the browser console on the page in question. It fetches the HTML as served, applies the same rule, prints every flagged image as a table, splits "no alt attribute" from alt="", and then reads the live page for the cases above:

const html = await (await fetch(location.href)).text();
const doc = new DOMParser().parseFromString(html, 'text/html');
const imgs = [];
(function walk(node) {
  for (const el of node.children) {
    if (el.localName === 'noscript') continue;
    if (el.localName === 'img' && el.getAttribute('src')) imgs.push(el);
    walk(el.localName === 'template' ? el.content : el);
  }
})(doc);
const rows = imgs.map(i => ({ src: i.getAttribute('src'), alt: i.getAttribute('alt') }));
const flagged = rows.filter(r => r.alt === null || !r.alt.trim());
console.table(flagged);
console.log('onpage-image-alt-missing:', flagged.length ? 'FAIL' : 'pass',
  '(' + flagged.length + ' of ' + rows.length + ' images)');
console.log('no alt attribute:', flagged.filter(r => r.alt === null).length,
  '| alt="" or blank (fine if decorative):', flagged.filter(r => r.alt !== null).length);
const live = [...document.images].filter(i => i.getAttribute('src'));
console.log('images after JS:', live.length, 'vs', rows.length, 'in HTML',
  '| hidden on screen:', live.filter(i => !i.checkVisibility()).length,
  '| role=presentation/none or aria-hidden:',
  live.filter(i => i.matches('[role=presentation],[role=none],[aria-hidden=true]')).length);

Work through the "no alt attribute" rows first. Those are the ones a screen reader may read out as a file name. For each alt="" row, decide whether the image carries information. If it does, describe it. If it doesn't, leave it as it is. If the live page has more images than the served HTML, the extra ones are added by JavaScript and are not part of this check.

Writing alt text that does its job

• Describe what the image tells the reader, in the context of the page. A product photo on a product page names the product and the detail that matters. The same photo in a size guide might describe the fit.
• Linked images: the alt text is the link text, so describe where the link goes. A logo that links home can say the site name.
• Charts and screenshots: give the point the image makes, and put the full data in the text nearby if it doesn't fit in a sentence.
• No keyword lists. Google names it as a spam risk, and a screen reader user hears every word.
• Decoration gets alt="", never a missing attribute.

How to fix alt text issues (by platform)

Where each platform keeps the alt field, and how to fill it in bulk:

• WordPress →
• Shopify →
• Webflow →
• Wix →
• Squarespace →

A logo or icon flagged many times usually comes from the theme header or footer template, not from your content, so fix it there once. The image used when your page is shared on social media is set separately; see Open Graph tags explained. Headings that wrap an image take their text from its alt, which our heading checks describe.

FAQ