Missing Alt Text | Blue Frog Docs

Missing Alt Text

Diagnose and fix missing or inadequate alt text to make images accessible to screen reader users

Missing Alt Text

What This Means

Alt text (alternative text) is a written description of an image that screen readers announce to users who can't see the image. Missing or poor alt text prevents blind and visually impaired users from understanding image content, creating an incomplete and potentially unusable experience.

Impact on Your Business

Legal Compliance:

  • Alt text is required under ADA and WCAG 2.1 Level A
  • Missing alt text is one of the most common accessibility violations
  • Can result in legal action and fines
  • Essential for Section 508 compliance

User Experience:

  • 15% of the global population has some form of visual impairment
  • Screen reader users rely entirely on alt text to understand images
  • Poor alt text creates frustrating, incomplete experience
  • Excludes users who could be customers

SEO Benefits:

  • Search engines use alt text to understand images
  • Improves image search rankings
  • Helps with overall content relevance
  • Context signals improve page understanding

Additional Benefits:

  • Alt text displays when images fail to load
  • Helps users on slow connections understand content
  • Provides context in text-only browsers
  • Improves content accessibility for AI tools

How to Diagnose

  1. Install WAVE Extension
  2. Navigate to your webpage
  3. Click the WAVE icon
  4. Review the sidebar:
    • Red alert icons indicate missing alt text
    • Feature icons show images with alt text
    • Click icons to see specific elements

What to Look For:

  • Red "Missing alternative text" errors
  • Images marked with alert icons
  • Count of affected images
  • Specific image locations

Method 2: Chrome DevTools

  1. Open your website in Chrome

  2. Right-click an image → "Inspect"

  3. Look for alt attribute in HTML:

    <!-- Missing alt text -->
<img src="product.jpg">

<!-- Empty alt (decorative) -->
<img src="decoration.jpg" alt="">

<!-- Has alt text -->
<img src="product.jpg" alt="Red cotton t-shirt, front view">

  4. Or use Console:

    // Find all images without alt text
document.querySelectorAll('img:not([alt])').forEach(img => {
  console.log('Missing alt:', img.src);
});

// Find images with empty alt (might need text)
document.querySelectorAll('img[alt=""]').forEach(img => {
  console.log('Empty alt:', img.src);
});

What to Look For:

  • <img> tags without alt attribute
  • Images with alt="" that should have descriptions
  • Images with poor alt text (e.g., "image", "picture")

Method 3: axe DevTools

  1. Install axe DevTools Extension
  2. Open Chrome DevTools (F12)
  3. Navigate to "axe DevTools" tab
  4. Click "Scan ALL of my page"
  5. Review "Images must have alternate text" violations

What to Look For:

  • Number of violations
  • Specific elements highlighted
  • Severity level (Critical for missing alt)
  • Code snippets showing affected images

Method 4: Lighthouse Accessibility Audit

  1. Open Chrome DevTools (F12)
  2. Navigate to "Lighthouse" tab
  3. Select "Accessibility" category
  4. Click "Generate report"
  5. Look for:
    • "Image elements have [alt] attributes"
    • "Image elements have accessible names"

What to Look For:

  • Failed audit items
  • Number of affected images
  • Specific elements to fix
  • Impact on accessibility score

Method 5: Screen Reader Testing

  1. Install a screen reader:

    • NVDA (Windows, free)
    • VoiceOver (Mac, built-in: Cmd+F5)
    • ChromeVox (Chrome extension)

  2. Navigate to your page

  3. Use image navigation:

    • NVDA: G key to jump between images
    • VoiceOver: VO+Cmd+G for images

  4. Listen to what's announced

What to Look For:

  • "Image" or "Unlabeled graphic" (missing alt)
  • Filename announced instead of description
  • Vague descriptions ("image", "photo")
  • Overly verbose or redundant descriptions

General Fixes

Fix 1: Add Alt Text to All Informative Images

For images that convey information:

  1. Product images:

    <!-- Bad -->
<img src="shirt.jpg">

<!-- Good -->
<img src="shirt.jpg" alt="Red cotton t-shirt, front view">

  2. Informational graphics:

    <!-- Bad -->
<img src="chart.jpg" alt="Chart">

<!-- Good -->
<img src="chart.jpg" alt="Bar chart showing 40% increase in sales from Q1 to Q2 2024">

  3. Icons with meaning:

    <!-- Bad -->
<img src="download-icon.svg">

<!-- Good -->
<img src="download-icon.svg" alt="Download PDF">

  4. Logos:

    <!-- Bad -->
<img src="logo.png">

<!-- Good -->
<img src="logo.png" alt="BlueFrog Analytics">

Fix 2: Use Empty Alt for Decorative Images

For purely decorative images:

  1. Decorative graphics:

    <!-- Decorative divider -->
<img src="divider.png" alt="">

<!-- Decorative pattern -->
<img src="pattern.svg" alt="">

  2. When to use empty alt:

    • Image is purely decorative
    • Image doesn't convey information
    • Removing image wouldn't affect understanding
    • Adjacent text already describes content

  3. Why empty alt, not no alt:

    <!-- Bad - screen reader announces filename -->
<img src="decoration.png">

<!-- Good - screen reader skips image -->
<img src="decoration.png" alt="">

Fix 3: Write Effective Alt Text

Best practices for alt text:

  1. Be descriptive and specific:

    <!-- Vague -->
<img src="person.jpg" alt="Person">

<!-- Specific -->
<img src="person.jpg" alt="Woman in business suit presenting to team in conference room">

  2. Don't include "image of" or "picture of":

    <!-- Redundant -->
<img src="dog.jpg" alt="Image of a golden retriever puppy">

<!-- Better -->
<img src="dog.jpg" alt="Golden retriever puppy sitting in grass">

  3. Keep it concise (aim for < 150 characters):

    <!-- Too long -->
<img src="product.jpg" alt="This is a red cotton t-shirt that comes in sizes S, M, L, XL and features a crew neck, short sleeves, and is made from 100% organic cotton grown in sustainable farms">

<!-- Better -->
<img src="product.jpg" alt="Red organic cotton t-shirt with crew neck">

  4. Provide context-appropriate descriptions:

    <!-- E-commerce context -->
<img src="shoe.jpg" alt="Nike Air Max 270 running shoe, black with red accent">

<!-- Blog context (same image) -->
<img src="shoe.jpg" alt="Example of modern athletic shoe design">

  5. For text in images, include the text:

    <!-- Infographic with text -->
<img src="quote.jpg" alt="Quote from Steve Jobs: 'Design is not just what it looks like and feels like. Design is how it works.'">

Fix 4: Handle Complex Images

For charts, graphs, and complex visuals:

  1. Provide brief alt + detailed description:

    <img
  src="sales-chart.jpg"
  alt="Sales trend chart 2020-2024"
  aria-describedby="chart-description"
>
<div id="chart-description">
  <p>Line chart showing quarterly sales from 2020 to 2024.
     Sales started at $2M in Q1 2020, dipped to $1.5M in Q2 2020,
     then steadily increased to $5M by Q4 2024.</p>
</div>

  2. Alternative: Provide data table:

    <figure>
  <img src="chart.jpg" alt="Sales by quarter chart">
  <figcaption>
    <details>
      <summary>View data table</summary>
      <table>
        <tr><th>Quarter</th><th>Sales</th></tr>
        <tr><td>Q1 2024</td><td>$4.2M</td></tr>
        <tr><td>Q2 2024</td><td>$4.5M</td></tr>
      </table>
    </details>
  </figcaption>
</figure>

  3. For infographics:

    • Brief alt describing overall purpose
    • Full text alternative in surrounding content
    • Or link to text-only version

Fix 5: Fix Background Images with Content

CSS background images aren't accessible:

  1. Use foreground images instead:

    <!-- Bad - not accessible -->
<div style="background-image: url('product.jpg')"></div>

<!-- Good -->
<img src="product.jpg" alt="Premium wireless headphones">

  2. If background image is decorative:

    <!-- OK - purely decorative -->
<div style="background-image: url('pattern.svg')" role="presentation">
  <h2>Heading</h2>
  <p>Content...</p>
</div>

  3. If you must use background image with content:

    <div style="background-image: url('hero.jpg')" role="img" aria-label="Modern office workspace with natural lighting">
  <div class="content">
    <!-- Overlay content -->
  </div>
</div>

Fix 6: Handle Linked Images

Images inside links need appropriate alt:

  1. Image as link:

    <!-- Bad - no context -->
<a href="/product">
  <img src="product.jpg" alt="Product">
</a>

<!-- Good - describes destination -->
<a href="/product">
  <img src="product.jpg" alt="View red t-shirt product details">
</a>

  2. Logo link:

    <!-- Home page link -->
<a href="/">
  <img src="logo.png" alt="BlueFrog Analytics home">
</a>

  3. Image + text link:

    <!-- Alt describes image, text provides link context -->
<a href="/article">
  <img src="thumbnail.jpg" alt="Woman using laptop">
  <span>How to Improve Website Performance</span>
</a>

<!-- Or use empty alt to avoid redundancy -->
<a href="/article" aria-label="How to Improve Website Performance">
  <img src="thumbnail.jpg" alt="">
  <span>How to Improve Website Performance</span>
</a>

Fix 7: Use ARIA When Appropriate

For icon fonts and SVGs:

  1. Icon fonts:

    <!-- Font Awesome icon -->
<i class="fa fa-download" aria-hidden="true"></i>
<span class="sr-only">Download</span>

<!-- Or -->
<button aria-label="Download file">
  <i class="fa fa-download" aria-hidden="true"></i>
</button>

  2. Inline SVG:

    <!-- Decorative SVG -->
<svg aria-hidden="true">...</svg>

<!-- Informative SVG -->
<svg role="img" aria-label="Download icon">
  <title>Download</title>
  ...
</svg>

  3. SVG as img:

    <img src="icon.svg" alt="Search">

Platform-Specific Guides

Detailed implementation instructions for your specific platform:

Platform Troubleshooting Guide
Shopify Shopify Alt Text Guide
WordPress WordPress Alt Text Guide
Wix Wix Alt Text Guide
Squarespace Squarespace Alt Text Guide
Webflow Webflow Alt Text Guide

Verification

After adding alt text:

  1. Re-run WAVE:

    • Verify red alert icons are gone
    • Confirm images show feature icons (not errors)
    • Check for any remaining issues

  2. Test with screen reader:

    • Navigate to page with screen reader
    • Use image navigation commands
    • Verify meaningful descriptions are announced
    • Confirm decorative images are skipped

  3. Run Lighthouse audit:

    • Generate new accessibility report
    • Verify image alt text audits pass
    • Check improved accessibility score

  4. Manual review:

    • Read all alt text in context
    • Verify descriptions are accurate and helpful
    • Check that decorative images have empty alt
    • Ensure no redundancy with surrounding text

Common Mistakes

  1. Using filename as alt - "IMG_1234.jpg" isn't helpful
  2. Writing "image of" or "picture of" - Redundant
  3. Alt text too vague - "Product" vs "Red cotton t-shirt"
  4. Missing alt entirely - Screen readers announce filename
  5. Alt text too long - Keep under 150 characters, use aria-describedby for details
  6. Decorative images with descriptions - Use empty alt instead
  7. CSS background images for content - Not accessible
  8. Redundant alt text - Repeating adjacent text
  9. Using title instead of alt - Title is not a substitute for alt
  10. Generic descriptions - Be specific and contextual

Alt Text Decision Tree

Is the image meaningful (conveys information)?
├─ YES: Does the image contain text?
│  ├─ YES: Include the text in alt
│  └─ NO: Write descriptive alt text
│     └─ Is it a complex image (chart, graph, diagram)?
│        ├─ YES: Brief alt + detailed description (aria-describedby)
│        └─ NO: Concise descriptive alt (< 150 chars)
│
└─ NO (purely decorative)
   └─ Use alt="" (empty alt attribute)

Additional Resources

↑ Back to top
// SYS.FOOTER