Last updated
Alt Text Requirements by Image Type
The Image Alt Text Checker evaluates alt text based on WCAG 2.1 Success Criterion 1.1.1. Different image types have different requirements:
/* Informative image — needs descriptive alt text */
<!-- Bad: missing alt -->
<img src="revenue-chart.png">
<!-- Bad: filename as alt -->
<img src="revenue-chart.png" alt="revenue-chart.png">
<!-- Bad: generic alt -->
<img src="revenue-chart.png" alt="image">
<!-- Good: descriptive alt -->
<img src="revenue-chart.png" alt="Bar chart showing Q1 revenue of $2.4M, up 18% from Q4">
/* Decorative image — use empty alt */
<!-- Bad: no alt attribute (screen reader announces filename) -->
<img src="divider-line.png">
<!-- Bad: descriptive alt on decorative image (unnecessary noise) -->
<img src="divider-line.png" alt="A decorative horizontal line">
<!-- Good: empty alt tells screen readers to skip it -->
<img src="divider-line.png" alt="">
/* Functional image (button/link) — describe the action */
<!-- Bad: describes appearance, not function -->
<a href="/search"><img src="magnifying-glass.png" alt="Magnifying glass icon"></a>
<!-- Good: describes the function -->
<a href="/search"><img src="magnifying-glass.png" alt="Search"></a>
/* Logo — include company name -->
<img src="logo.png" alt="Acme Corporation">
<!-- If logo is inside a link to homepage: -->
<a href="/"><img src="logo.png" alt="Acme Corporation — Home"></a>Alt Text Quality Scoring
The checker scores alt text quality and flags common problems:
/* Too short — may not be descriptive enough */
<img src="team-photo.jpg" alt="Team">
⚠ Alt text is only 1 word. Consider adding more detail.
Suggestion: "Engineering team of 12 people at the 2024 company retreat"
/* Too long — may be truncated by screen readers */
<img src="product.jpg" alt="This is a high-quality red ceramic coffee mug with a comfortable handle, 12oz capacity, dishwasher safe, available in red, blue, and green colors, perfect for home or office use">
⚠ Alt text is 185 characters. Screen readers may truncate at 125 characters.
Suggestion: "Red ceramic coffee mug, 12oz, dishwasher safe"
/* Redundant prefix */
<img src="sunset.jpg" alt="Image of a sunset over the ocean">
⚠ Alt text starts with "Image of" — screen readers already announce it's an image.
Suggestion: "Sunset over the Pacific Ocean with orange and pink sky"
/* Keyword stuffing */
<img src="shoes.jpg" alt="buy shoes cheap shoes discount shoes running shoes">
✗ Alt text appears to be keyword-stuffed. Write for users, not search engines.
/* Good alt text */
<img src="shoes.jpg" alt="Blue Nike Air Max running shoes, size 10">
✓ Clear, descriptive, appropriate length (47 characters)Complex Images — Charts and Graphs
Charts and graphs need more than a brief alt text. Use a combination of alt and a longer description:
/* Simple chart — alt text summarizes the key insight */
<img
src="sales-chart.png"
alt="Line chart: monthly sales grew from $1.2M in January to $2.8M in December 2023">
/* Complex chart — use figure + figcaption + aria-describedby */
<figure>
<img
src="complex-chart.png"
alt="Stacked bar chart showing market share by region"
aria-describedby="chart-description">
<figcaption id="chart-description">
North America leads with 42% market share, followed by Europe at 31%,
Asia-Pacific at 19%, and Rest of World at 8%. North America grew 5%
year-over-year while Asia-Pacific grew 12%.
</figcaption>
</figure>
/* Data table as alternative to chart */
<img src="data-chart.png" alt="See table below for data" aria-describedby="data-table">
<table class="data-table" id="data-table">
<caption>Regional Market Share 2023</caption>
<thead>
<tr><th>Region</th><th>Share</th><th>YoY Change</th></tr>
</thead>
<tbody>
<tr><td>North America</td><td>42%</td><td>+5%</td></tr>
<tr><td>Europe</td><td>31%</td><td>+2%</td></tr>
<tr><td>Asia-Pacific</td><td>19%</td><td>+12%</td></tr>
</tbody>
</table>Checker Report Output
The checker generates a report of all images on a page with their status:
/* Sample checker report for https://example.com/products */
Total images found: 24
✓ Pass: 18 images (75%)
⚠ Warning: 4 images (17%)
✗ Fail: 2 images (8%)
FAILURES (must fix):
Line 45: <img src="/images/hero.jpg">
✗ Missing alt attribute entirely
Fix: Add alt="[descriptive text]" or alt="" if decorative
Line 112: <img src="/images/product-123.jpg">
✗ Alt text is filename: "product-123.jpg"
Fix: Describe the product shown in the image
WARNINGS (should fix):
Line 67: <img src="/icons/arrow.png" alt="arrow">
⚠ Generic alt text — is this decorative? If so, use alt=""
If functional, describe what it does: alt="Next page"
Line 89: <img src="/team/ceo.jpg" alt="Photo of our CEO Jane Smith smiling in a professional headshot taken at the company headquarters in San Francisco California">
⚠ Alt text is 142 characters — consider shortening
Suggestion: "Jane Smith, CEO of Acme Corporation"
SEO OPPORTUNITIES:
Line 78: <img src="/products/widget-pro.jpg" alt="Widget">
⚠ Alt text could include product keywords
Suggestion: "Widget Pro — stainless steel desk organizer"Automated Alt Text Checking in CI
Integrate alt text checking into your build pipeline to catch issues before deployment:
/* Using axe-core for automated accessibility testing */
const { AxePuppeteer } = require('@axe-core/puppeteer');
const puppeteer = require('puppeteer');
async function checkAltText(url) {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto(url);
const results = await new AxePuppeteer(page)
.withRules(['image-alt', 'image-redundant-alt'])
.analyze();
const violations = results.violations;
violations.forEach(v => {
console.log(`✗ ${v.id}: ${v.description}`);
v.nodes.forEach(n => console.log(` ${n.html}`));
});
await browser.close();
return violations.length === 0;
}
/* Jest test */
test('all images have appropriate alt text', async () => {
const passed = await checkAltText('http://localhost:3000');
expect(passed).toBe(true);
});