How to Fix Missing Alt Text on Images: A Step-by-Step Guide for WCAG 2.1 Compliance

Missing alt text is the single most common WCAG violation found on the web — and one of the most frequently cited issues in ADA accessibility lawsuits. In 2023 alone, over 4,600 federal accessibility lawsuits were filed, with image alt text failures appearing in the majority of complaints. If you're running a business website, an e-commerce store, or a web application, learning how to fix missing alt text isn't optional anymore. It's risk management.

The good news: this is one of the most straightforward accessibility fixes you can make. This guide walks you through exactly what to do.

Why Missing Alt Text Is a Legal and UX Problem

Screen readers like JAWS, NVDA, and Apple's VoiceOver announce image content to users who are blind or have low vision. When an image has no alt attribute, the screen reader either skips it entirely or reads out the raw file name — something like "IMG_20231104_094523.jpg" — which is useless or actively confusing.

Under WCAG 2.1 Success Criterion 1.1.1 (Non-text Content), every non-decorative image must have a text alternative that serves the equivalent purpose. This requirement maps directly to the ADA's Title III provisions for public accommodations, which courts have increasingly applied to websites.

The financial exposure is real: demand letters from accessibility law firms typically settle for $10,000–$25,000, and serial plaintiffs often target the same site multiple times if the underlying issues aren't fully resolved.

Step 1: Audit Your Images First

Before you fix anything, you need a complete inventory of your accessibility violations. Manually inspecting every image is impractical for most sites. Use a combination of:

• Automated scan (catches missing or empty alt attributes instantly)
• Manual review (catches alt text that exists but is meaningless or wrong)

In your browser's developer tools, you can run a quick check with this JavaScript snippet in the console:

document.querySelectorAll('img:not([alt])').forEach(img => {
  console.log('Missing alt:', img.src);
});

This surfaces every image that's missing the alt attribute entirely. It won't catch empty alt text (alt="") or poor-quality descriptions, but it's a fast first pass.

Step 2: Understand the Three Types of Images

Knowing how to fix missing alt text correctly means understanding that not every image needs the same treatment. WCAG distinguishes between three categories:

Informative Images

These convey meaningful content — product photos, charts, infographics, photos of people or places. They need descriptive alt text.

<!-- Wrong -->
<img src="red-running-shoes.jpg">

<!-- Right -->
<img src="red-running-shoes.jpg" alt="Red lightweight running shoes with white sole, size 10">

Decorative Images

Background textures, dividers, purely aesthetic icons — these should have an empty alt attribute so screen readers skip them entirely.

<!-- Correct for decorative images -->
<img src="divider-line.png" alt="">

Setting alt="" is intentional and correct. Do NOT omit the attribute entirely — that's the violation.

Functional Images

Buttons, links, and icons that trigger an action. The alt text should describe the function, not the image.

<!-- Wrong -->
<img src="search-icon.png" alt="magnifying glass">

<!-- Right -->
<img src="search-icon.png" alt="Search">

<!-- Or better, use CSS for decorative icons and ARIA for function -->
<button aria-label="Search">
  <img src="search-icon.png" alt="">
</button>

Step 3: Write Alt Text That Actually Works

Bad alt text is nearly as harmful as missing alt text. Here are the rules:

Do:
- Describe the content and context, not just the object ("Bar chart showing 40% revenue increase in Q3 2024" not "chart")
- Keep it under 125 characters when possible
- Include relevant keywords naturally — this also helps SEO
- Describe the emotional tone for marketing images when relevant

Don't:
- Start with "Image of..." or "Photo of..." — screen readers already announce it's an image
- Stuff keywords for SEO purposes only — WCAG auditors and plaintiffs' attorneys check for this
- Use the filename or generic terms like "image1"
- Write the same alt text for every image on the page

Step 4: Fix Alt Text in Your CMS or Codebase

WordPress

Every image in the Media Library has an "Alt Text" field. Fill it in when uploading. For existing images, go to Media > Library, click each image, and add alt text in the sidebar panel. The Gutenberg block editor also lets you add alt text directly in the image block settings.

Shopify

In the admin panel, go to Products > [Product] > Images, click the image, and add alt text in the pop-up dialog. For theme images in Liquid templates, update the img_tag filter:

{{ image | img_tag: alt }}

Make sure alt is assigned a meaningful string variable, not left blank.

React / Next.js

If you're using Next.js Image component, the alt prop is required — the build will warn you if it's missing. Still, "required" doesn't mean "correct":

// Technically valid but useless
<Image src="/hero.jpg" alt="image" width={800} height={400} />

// Actually compliant
<Image src="/hero.jpg" alt="Small business owner reviewing analytics on laptop" width={800} height={400} />

Raw HTML / Static Sites

Do a project-wide search for <img tags without alt attributes. In VS Code, use the regex search:

<img(?![^>]*alt=)

This flags every img tag missing the alt attribute so you can address them one by one.

Step 5: Test Before You Ship

After making fixes, verify them with actual assistive technology — not just automated tools. Free options:

• NVDA (Windows, free) — most widely used screen reader
• VoiceOver (Mac/iOS, built-in) — press Cmd+F5 to enable
• axe DevTools browser extension — catches WCAG violations in real time

Tab through your pages and listen. If the announced image descriptions make sense in context without seeing the screen, you've done it right.

This Is Fixable — But You Have to Know Where to Start

The hardest part of learning how to fix missing alt text at scale is finding every violation before a plaintiff's attorney does. A single overlooked product image or decorative icon without alt="" can reopen your legal exposure.

Manual audits are time-consuming and incomplete. An automated scan gives you a complete, prioritized list — including the exact lines of code that need to change.

Scan your site for free at wcagrepair.com and get a remediation guide with exact code fixes for $8.99. You'll know every missing alt text violation on your site within minutes — and exactly how to resolve each one.