Prepared Docs

Prepared Docs

⌘K

    Loading navigation…

User

  1. Components
  2. Image
  3. Accessibility

Image

Accessibility

Image requires an alt prop in both URL and inline SVG modes. How that value is exposed depends on whether the image conveys meaning.

Alt text

  • Meaningful images: Provide a concise alt that describes purpose or content (for example, "Prepared logo" or "Officer profile photo").
  • Decorative images: Pass alt="" when the image adds no information beyond surrounding text or UI chrome.

Do not omit alt or use placeholder strings like "image" when the image carries meaning.

URL mode (src)

Renders a native <img> with the alt attribute forwarded directly. Screen readers announce the alt text as the image label.

Inline SVG mode (svg)

Accessibility attributes are applied to the <svg> node:

  • Non-decorative (alt non-empty): role="img" and aria-label={alt}.
  • Decorative (alt=""): aria-hidden={true} and focusable={false}.

Themed modes (lightSrc/darkSrc, lightSvg/darkSvg)

Both theme variants mount in the DOM, but the inactive variant uses display: none and is removed from the accessibility tree. Assistive tech announces a single image — the visible variant — with the shared alt value. Pass id once; it is applied to a display: contents themed root so the document keeps a single stable id without JavaScript theme branching (and without duplicating id on both variants).

Best practices

  • Do not convey critical information by image alone — pair logos, status marks, or charts with visible text.
  • Test decorative treatment: if removing the image would confuse sighted users, it is not decorative and needs descriptive alt text.
  • For URL SVGs loaded via src, the browser treats them like raster images; alt text behavior matches standard <img> semantics.

Previous

Image / API and Development

Next

Input / Usage

On this page

Alt text
URL mode (src)
Inline SVG mode (svg)
Themed modes (lightSrc/darkSrc, lightSvg/darkSvg)
Best practices