A practical field guide

SVG alt text: examples that say the right thing

The right label depends on what the graphic does on this page. A meaningful illustration needs a useful name. A decorative flourish needs to stay quiet. An icon inside a labeled button usually needs no separate announcement.

Use these patterns as starting points, then check them in the context of the page. The free SVG Ready checker flags common markup issues and creates copy-ready HTML or React snippets; it cannot decide what your graphic means or replace a full accessibility review.

1. An SVG image in an <img> element

For an informative external SVG, put its concise text alternative in the HTML alt attribute. Describe the information or action the graphic contributes, rather than its colors or the fact that it is an image.

<img src="payment-success.svg" alt="Payment received">

If the graphic adds no information beyond nearby text, use an empty alt value so assistive technology can skip it.

<img src="sparkle-divider.svg" alt="">

2. A meaningful inline SVG

When an inline SVG is a single meaningful graphic, give the SVG an image role and connect it to a short title. The title is text in the markup, so keep it concise and specific.

<svg role="img" aria-labelledby="chart-title" viewBox="0 0 240 120">
  <title id="chart-title">Monthly sign-ups rose from 18 to 42</title>
  <!-- graphic paths -->
</svg>

If the same information is already presented in a nearby table or paragraph, avoid repeating a second long description as the graphic's name. For a complex chart, provide the useful values and relationships as real page text as well.

3. A decorative inline SVG

Hide an inline SVG from the accessibility tree when it is purely decorative and contains no focusable or interactive content.

<svg aria-hidden="true" viewBox="0 0 24 24">
  <path d="…"></path>
</svg>

4. An icon inside a button or link

Name the control itself. If visible text already explains the action, hide the icon from assistive technology to prevent a second, redundant announcement.

<button type="button">
  <svg aria-hidden="true" viewBox="0 0 24 24">…</svg>
  Save changes
</button>

When an icon is the only content in a control, give the button or link an accessible name such as aria-label="Close dialog". The name should describe the action, not just the shape of the icon.

5. A quick review before shipping

• Decide whether the SVG is informative, functional, or decorative in this exact context.
• Use an empty alt="" for decorative SVGs loaded with <img>.
• Give meaningful external SVG images a short, useful alt.
• Give a meaningful inline SVG one clear name, and keep decorative paths out of the accessibility tree.
• For charts and diagrams, make the important information available as page text too.
• Test the page with a screen reader and keyboard; a markup checker cannot judge whether a description is accurate.

References

• W3C WAI: Images Tutorial — informative, decorative, and functional image alternatives.
• W3C WAI: Decorative Images — when and how to provide an empty text alternative.
• MDN: ARIA img role — naming a single inline SVG as an image.
• MDN: SVG title element — the SVG title element and accessible names.

← Back to SVG Ready