Documentation/Images need alt text

Images need alt text

ZMD004

Every <img> must carry a descriptive alt attribute or an explicit empty alt="" if purely decorative. Inline <svg> used as images (role="img") or icon-only links/buttons must have an accessible name via aria-label, aria-labelledby, or <title>.

✅ Good

<img src="team-photo.jpg" alt="Our design team standing outside the new office building">

<svg role="img" aria-label="Close"></svg>

<svg role="img"><title>Close</title></svg>

❌ Bad

<img src="team-photo.jpg">

<svg role="img"></svg>

<a href="/home"><svg></svg></a>

When: An <img> has no alt attribute or its alt is empty, or an inline <svg> used as an image/link/button lacks an accessible name

Warning: Image missing text alternative (alt or accessible name)

Solution: Add descriptive alt text, or add aria-label/aria-labelledby or <title> for inline SVG icons

Why it matters

Accessibility: Missing alt text leaves screen-reader users unaware of image content; null alt on informative images hides key information.

SEO: Without alt text, search engines lack context for images, reducing opportunities to rank in image search.

In brief

  • Goal: Make non-text content accessible through text alternatives.
  • What to do: Provide concise, descriptive alt text for informative images; use alt="" for purely decorative ones. For inline SVG icons used as images/controls, provide aria-label/aria-labelledby or a <title>.
  • Why: Text alternatives can be rendered in any modality—visual, auditory, or tactile—so no one misses key content.

Intent

Ensure that all visual content is perceivable by assistive technologies and remains meaningful when images fail to load, including inline SVG icons.

Benefits

  • Screen-reader users receive meaningful descriptions instead of “image” or nothing.
  • Keyboard-only users can skip decorative images and focus on relevant content.
  • Search engines index images based on alt text, improving discoverability.
  • Pages with broken images remain understandable via alt text fallback.

Techniques

  • G94: Providing text alternatives for non-text content using the alt attribute on <img> elements.
  • H67: Using null alt text (alt="") for decorative images, optionally with role="presentation".

HTML Semantics

The alt attribute’s value must convey the content or function of the image—avoid describing its format or filename. Inline SVGs use their accessible name (aria-label/aria-labelledby or <title>) as the text alternative.

References

Tips & edge cases

  • Decorative images: use alt="" and role="presentation" to skip them in assistive-tech navigation.
  • Informative images: keep alt text concise (a brief phrase or sentence), not a paragraph.
  • Linked images: ensure alt describes the link’s purpose (e.g., alt="Read our annual report").
  • Complex graphics: provide short alt plus a longer description via nearby text or aria-describedby.
  • Inline SVG icons: use aria-label/aria-labelledby or a <title> when the SVG conveys meaning or is the only content of a control.

See also