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.

How to verify the fix

Shipping the change is not the same as passing 1.1.1. Re-run these checks against the page you edited before you close the ticket.

• Navigate the page with a screen reader (VoiceOver, NVDA) and listen to image announcements.

• Run an automated scanner — alt issues are deterministically detectable.

• Disable images in your browser; if the page is now incomprehensible, alt text is missing.

What 1.1.1 requires

1.1.1 Non-text Content (Level A, Perceivable): All non-text content (images, icons, controls) must have a text alternative that serves the equivalent purpose. Screen readers cannot interpret pixels. Without alt text or accessible names, users who rely on assistive technology cannot understand product photos, navigation icons, decorative graphics, or interactive controls represented by images.

• Decorative images without alt="" (announced as "graphic")

  1.1.1

• Informative images with empty alt or alt="image" / alt="logo"

  1.1.1

• Icon-only buttons missing aria-label or visible text

  1.1.1

Priority: Critical

This is one of the findings that shows up in demand letters, because the barrier it creates is total rather than inconvenient: the affected user cannot complete the task at all. Treat it as a release blocker, not a backlog item.

Because the cause is almost always a shared component rather than a single page, fix it where the component is defined and re-scan the whole site. Record 1.1.1 on the ticket verbatim: that string is what an auditor, a procurement questionnaire or a regulator will search for.