SVG accessibility

Give SVG graphics accessible names and descriptions, hide decoration, respect reduced motion, and avoid common labeling mistakes.

An SVG that carries meaning needs a text alternative, and an SVG that is only decoration should be hidden from assistive technology. Most accessibility work on SVG comes down to deciding which of those two cases you have, then using the right markup for it.

Decide what the graphic is for

WCAG success criterion 1.1.1 (Level A) says non-text content needs a text alternative that serves an equivalent purpose. It lists exceptions, including content that is decorative or formatting only, which should be implemented so assistive technology can ignore it.

That gives you a short decision list:

  • Informative graphic (a chart, a diagram, a logo that identifies a brand): give it a name, and a longer description if the name cannot carry the meaning.
  • Decorative graphic (a flourish, a background shape): hide it.
  • Interactive graphic (an icon button, a clickable map region): the control needs an accessible name that describes its purpose, and it must work from the keyboard. See SVG with JavaScript for event handling.

Name an informative SVG

Put role="img" on the outer <svg> and give it a name. MDN’s guidance for role="img" is that screen readers then announce the graphic as one unit using its label, rather than reading each child node. Browsers also treat the descendants of an img role as presentational, so semantics you put inside, such as headings, are lost.

For the name itself you have three options. In the SVG Accessibility API Mappings working draft, the name is taken in this priority order: aria-labelledby, then aria-label, then a direct child <title>. A description comes from aria-describedby, then a direct child <desc>.

In practice, a <title> and <desc> pair, referenced by id from the root, covers the most ground:

Edit the <desc> text and consider what a person who cannot see the bars would learn. A good description states the point of the chart, not the colors.

Some trade-offs to know about:

  • MDN notes that <title> should be the first child of its parent for SVG 1.1 compatibility, and that browsers usually show it as a tooltip. The tooltip is a side effect, not a guarantee, and touch and keyboard users will not see it.
  • If visible text on the page already describes the graphic, MDN recommends pointing at that text with aria-labelledby instead of writing a <title>. That avoids two copies drifting apart.
  • Ids in aria-labelledby must be unique in the page. If you inline the same SVG twice, give each copy its own ids. Build tools that minify ids can cause clashes; the optimization guide covers this.
  • When the SVG is loaded with <img>, the HTML alt attribute is the name, as with any image. MDN lists alt for <img> and aria-label or aria-labelledby for other elements with role="img".

Hide decoration

If a shape adds nothing, remove it from the accessibility tree. The SVG-AAM draft says elements with aria-hidden="true" should not be exposed, and so are elements with role="none" or role="presentation" (unless they are focusable).

Here the label on the root carries the meaning, and the dots are marked decorative. The draft also says purely presentational containers and shapes are omitted from the tree unless they carry a title, description, label, role or tabindex, so you often do not need to do anything for plain shapes. Marking them explicitly makes your intent clear and protects you if a tool adds a stray <title> later.

Use graphics roles for complex diagrams

The WAI-ARIA Graphics Module (a W3C Recommendation from October 2018) defines three roles for structured graphics:

  • graphics-document for a self-contained graphic whose layout carries meaning, such as a chart, map or technical drawing. Its name must come from you.
  • graphics-object for a meaningful part inside it, such as the door in a drawing of a house.
  • graphics-symbol for an atomic icon-like part where meaning matters more than appearance, such as repeated symbols on a floor plan. The spec suggests aria-roledescription to name the symbol type.

The module suggests fallbacks for older assistive technology: document for graphics-document, group for graphics-object, and img for graphics-symbol. I have not verified how consistently screen readers support these roles today, so treat them as an enhancement. A simple role="img" with a good description is the safer default. If a diagram has parts that users need to explore one by one, test it with real assistive technology before shipping.

Respect motion preferences

Animation raises two separate issues.

First, WCAG 2.2.2 (Level A) requires a way to pause, stop or hide moving content that starts automatically, lasts more than five seconds and runs alongside other content, unless the movement is essential. Auto-updating content has no five-second exemption.

Second, MDN notes that motion such as scaling or panning large objects can trigger discomfort for people with vestibular disorders. The prefers-reduced-motion media feature has two values, no-preference and reduce, and the MDN example swaps a strong animation for a gentler one instead of always removing it.

Because a media query changes CSS rules, animation defined in CSS can be adjusted from inside the SVG’s own <style> element:

Turn on your operating system’s reduced-motion setting and reload to see the difference. This pulse runs forever, so on a real page it would also need a pause control. SMIL is another way to animate SVG without script, but I have not verified that a CSS media query can switch SMIL off, so for anything that must honor the preference, define the animation in CSS or control it from your own code. See SVG animation for the options.

Check your work

  • Inspect the accessibility tree in your browser’s developer tools and confirm the name and description you expect.
  • Tab through the page. Anything interactive must be reachable and must show focus.
  • Test with at least one screen reader. Some combinations announce labels twice, as MDN warns for role="img".
  • Check color contrast for text and for meaningful shapes. A chart that relies on color alone fails users with color vision differences; add labels, patterns or direct annotations. The same applies to interactive infographics.
  • If you build with a framework, make sure your icon components accept a label prop and default to hidden when none is given. SVG in frontend frameworks shows the pattern.

Accessible SVG is mostly a labeling habit. Name what matters, hide what does not, and keep motion under the user’s control.

Sources

Checked against these references on 2026-11-21.