How to fix missing image alt text

What "alt text" actually is

The alt attribute on an <img> is the text a screen reader announces in place of the picture, the text a browser shows if the image fails to load, and part of what search engines read. WCAG 2.1 success criterion 1.1.1 (Non-text Content, Level A) requires a text alternative for every image that carries meaning. Note the level: this is an A requirement, the most basic tier — a missing alt is not a nitpick, it's a floor you're expected to clear.

Three kinds of image, three different answers

Good alt text isn't about filling in a box; it's about deciding what role the image plays. Almost every image is one of three types, and each is handled differently.

1. Informative images

The image conveys information the surrounding text doesn't. Describe the information, not the file. Aim for the shortest phrase that carries the same meaning a sighted reader gets at a glance.

<img src="chart.png">
<img src="chart.png" alt="chart.png">
<img src="chart.png" alt="image">

<img src="chart.png"
     alt="Revenue grew from €1.2M in 2023 to €3.4M in 2025.">

2. Decorative images

The image is pure decoration — a divider flourish, a background texture, an icon sitting next to text that already says the same thing. Here you want the screen reader to skip it. Give it an explicitly empty alt so it's announced as nothing, rather than leaving the attribute off (which makes some screen readers fall back to reading the filename).

<img src="swirl-divider.svg" alt="">

3. Functional images

The image does something — it's inside a link or a button. The alt text must describe the action or destination, not the picture. A magnifying-glass icon that submits a search should read "Search", not "magnifying glass".

<a href="/warenkorb">
  <img src="cart.svg" alt="View your cart">
</a>

Rules of thumb for writing it

• Don't start with "Image of…" or "Picture of…" — the screen reader already says "image".
• Keep it tight. If you need a paragraph, put that in the page text and keep the alt a summary.
• Don't stuff keywords. Alt text that reads like SEO spam hurts real users and can look manipulative.
• For a logo that links home, "Company name, home" beats "logo".

How our scanner detects it

We check every <img> for the presence of an alt attribute (or an equivalent accessible name via aria-label / aria-labelledby). A missing attribute is a clear failure we report with the element's selector. But here's the honest limit: we can tell that alt text exists, we cannot tell whether it's good. An image labelled "photo" technically passes the automated check yet helps nobody. That judgement — is this alt text actually meaningful? — is exactly the kind of thing we flag for manual review, and it's a big part of why a scanner alone can't certify compliance.