How to fix: missing alt text on images

What it looks like in the wild

Screen readers announce "graphic" or read out the file path. Images convey no meaning.

The screen-reader user, keyboard user, or low-vision user encountering this issue does not get an error message. The page just stops working for them. Which is why this kind of bug rarely shows up in your error tracker; it shows up in support tickets, lawsuits, and abandoned conversions.

Why it fails WCAG

Every <img> must have an alt attribute. Use alt="" for decorative images, descriptive text for informative ones.

The wrong pattern (avoid)

<img src="/team.jpg">

The right pattern (copy this)

<img src="/team.jpg" alt="Five product engineers reviewing a design on a screen">
<!-- Decorative: -->
<img src="/divider.svg" alt="">

Notes from real audits

• Filename as alt is worse than no alt — it confuses screen readers.

• For complex charts, add a longer text alternative nearby (figcaption or aria-describedby).

• CSS background-images with meaning need an <img> equivalent or text in the DOM.

Related fixes