Images need alt text or be decorative

Images must not lack alternative text; decorative images need empty alt

Intro:

Every meaningful image needs alternative text, and purely decorative images must have alt="" so assistive technology skips them. This applies to photos, icons, charts, logos, and images used in links or buttons. Users of screen readers and those with low vision rely on this text to understand your content.

Why It Matters

Without a text alternative, screen reader users miss information conveyed by images, which can break context, instructions, or data. A missing or vague alt can also make interactive elements unusable.

Poor or redundant descriptions slow navigation and increase cognitive load. Clear, concise alt text preserves meaning and keeps experiences efficient for blind and low‑vision users.

For icons used as controls, the text alternative is the only way many users can discover the control’s purpose and action.

Common Causes

• Omitted alt attributes on <img> from templates or CMS defaults
• Using file names or generic words (e.g., "image", "photo") as alt text
• Relying on aria-label/aria-labelledby on <img> instead of the required alt attribute
• Leaving decorative or spacer images with non-empty alt, causing noise in screen readers
• Icon-only buttons/links with no accessible name
• Complex charts/infographics lacking a nearby text summary or data table

How to Fix

1. Inventory images:
   • List all <img>, inline <svg>, and CSS background images used as content or controls.
2. Classify each image:
   • Informative: conveys content (photos, diagrams, logos used as content).
   • Functional: inside a link or button; triggers navigation or an action.
   • Decorative/redundant: purely visual, or duplicated by adjacent text (e.g., a divider, a bullet icon, or an image next to identical link text).
   • Complex: charts/infographics where a short alt cannot convey all details.
3. Write alt for informative images:
   • Describe the image’s purpose in context. Be specific but brief.
   • Recommendation: keep it succinct (often under ~100–150 characters when possible).
   • Don’t start with “image of” or repeat surrounding captions.
   • Logos: alt should be the organization name.
4. Provide alt for functional images:
   • Alt text must state the action or destination (e.g., “Download invoice” for an icon inside a link to a PDF).
   • If the link or button already has visible text, set the image alt="" to avoid duplication.
5. Mark decorative/redundant images to be ignored:
   • Use alt="" on <img>. Do not omit the alt attribute.
   • Optionally add role="presentation" or role="none" in addition to alt="".
6. Do not use ARIA to replace alt on <img>:
   • The alt attribute is required for <img>. Avoid aria-label/aria-labelledby as a substitute.
   • If using an icon via CSS background (no <img>), ensure the containing control has an accessible name (visible text or aria-label on the button/link).
7. Handle complex images:
   • Provide a concise alt that names the graphic and its takeaway.
   • Add a nearby detailed description, data table, or link to a full description.
   • Use <figure> and <figcaption> where helpful.
8. Inline SVGs:
   • Give the <svg> role="img" and provide an accessible name via <title> or aria-labelledby.
9. Bake it into your process:
   • Update component libraries so image components require alt or intentionally set alt="".
   • Train content editors on when to use alt versus alt="".

How to Test

Keyboard check (for functional images):

• Tab to all image-based links and buttons. Ensure they are focusable and the focus outline is visible.
• Confirm the accessible name communicates the action; do not rely on the icon alone.

Screen reader check:

• With NVDA/JAWS (Windows) or VoiceOver (macOS/iOS), navigate images:
• Informative images are announced with meaningful alt.
• Decorative images are skipped entirely.
• Icon buttons/links announce clear action names.
• Complex graphics have a nearby detailed description users can reach.

Mobile/touch check:

• With VoiceOver (iOS) or TalkBack (Android), explore by touch. Verify images read as above and that touch targets for image-based controls remain usable.

Quick automated checks:

• Run axe, Lighthouse, or similar to flag <img> without alt and empty links/buttons.
• Spot-check HTML for <img> missing the alt attribute and for decorative images that forgot alt="".

Good Example

<!-- Informative photo -->
<img src="/images/support-team.jpg" alt="Support agents assisting customers in the call center">

<!-- Decorative divider -->
<img src="/assets/divider.svg" alt="" role="presentation">

<!-- Functional icon in a link -->
<a href="/invoices/12345.pdf">
  <img src="/icons/download.svg" alt="Download invoice">
</a>

<!-- Inline SVG with accessible name -->
<svg role="img" aria-labelledby="logo-title" width="120" height="30">
  <title id="logo-title">Acme Robotics</title>
  <!-- svg paths -->
</svg>

Bad Example

<!-- Missing alt entirely -->
<img src="/images/hero.jpg">

<!-- Meaningless alt -->
<img src="/charts/sales-q4.png" alt="image">

<!-- Trying to replace alt with ARIA (don’t) -->
<img src="/brand/logo.png" aria-label="Acme Robotics">

<!-- Icon-only control with no name -->
<button class="icon-print"></button>

Quick Checklist

• Every <img> has an alt attribute; never leave it out
• Informative images: short, contextual alt that conveys purpose
• Functional images: alt states the action or destination
• Decorative/redundant images: alt="" (optionally role="presentation"/"none")
• Do not use aria-label/aria-labelledby instead of alt on <img>
• Icon-only controls have an accessible name on the control
• Complex images include a concise alt and a nearby long description or data table
• Inline SVGs expose an accessible name via <title> or aria-labelledby