# SVG elements with an img, graphics-document, or graphics-symbol role must have an accessible name via a <title> element, aria-label, or aria-labelledby.

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/accesslint/0.16/text-alternatives/svg-img-alt
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

When an `<svg>` element has an explicit role of `img`, `graphics-document`, or `graphics-symbol`, it is treated as meaningful content in the accessibility tree. Screen readers will announce it to users, but without an accessible name, there is nothing useful to announce. The user knows something is there but has no way to understand what it represents. This is the SVG equivalent of an `<img>` tag missing its `alt` attribute.

This rule maps to WCAG 2.0 success criterion 1.1.1 (Non-text Content), a Level A requirement. It states that all non-text content presented to users must have a text alternative that serves the same purpose. Since SVG graphics are non-text content, any SVG that carries meaning needs a text description that screen reader users can access.

Browser and assistive technology support for SVG accessibility is inconsistent. The `<title>` and `<desc>` elements inside SVGs are not reliably exposed to screen readers across all browser and assistive technology combinations. Using WAI-ARIA attributes (`aria-label` or `aria-labelledby`) alongside the `img` role gives the most reliable results across browsers.

## How to fix it

There are three ways to give an SVG element an accessible name:

1. Add a `<title>` element as the first child of the `<svg>`. This is the native SVG mechanism for providing a name, though support varies across assistive technologies.
2. Add an `aria-label` attribute directly on the `<svg>` element with a short text description.
3. Use `aria-labelledby` to reference one or more elements that contain the text alternative. This is useful for complex SVGs where you want to combine a `<title>` and a `<desc>`.

For the most reliable screen reader support, combine a `<title>` element with `aria-labelledby` pointing to it.

If the SVG is purely decorative and does not convey any information, do not give it one of these roles. Instead, add `aria-hidden="true"` to remove it from the accessibility tree entirely.

## Examples

### Missing accessible name (incorrect)

This SVG has `role="img"` but no `<title>`, `aria-label`, or `aria-labelledby`. A screen reader will announce it as an image with no description.

```html
<svg xmlns="http://www.w3.org/2000/svg" role="img" width="100" height="100">
  <circle cx="50" cy="50" r="40" fill="yellow"></circle>
</svg>
```

### Using a `<title>` element (correct)

Adding a `<title>` as the first child provides an accessible name. The `aria-labelledby` attribute referencing the `<title>` improves cross-browser support.

```html
<svg xmlns="http://www.w3.org/2000/svg" role="img" width="100" height="100"
  aria-labelledby="circle-title">
  <title id="circle-title">Yellow circle</title>
  <circle cx="50" cy="50" r="40" fill="yellow"></circle>
</svg>
```

### Using `aria-label` (correct)

A short `aria-label` on the `<svg>` element itself is the simplest approach and has good assistive technology support.

```html
<svg xmlns="http://www.w3.org/2000/svg" role="img" width="100" height="100"
  aria-label="Yellow circle">
  <circle cx="50" cy="50" r="40" fill="yellow"></circle>
</svg>
```

### Using `aria-labelledby` with `<title>` and `<desc>` (correct)

For complex graphics, reference both a `<title>` and a `<desc>` to give users a name and a longer description.

```html
<svg xmlns="http://www.w3.org/2000/svg" role="img" width="200" height="200"
  aria-labelledby="chart-title chart-desc">
  <title id="chart-title">Quarterly sales chart</title>
  <desc id="chart-desc">Bar chart showing sales rising from 50 units in Q1 to 120 units in Q4.</desc>
  <rect x="10" y="150" width="40" height="50" fill="steelblue"></rect>
  <rect x="60" y="80" width="40" height="120" fill="steelblue"></rect>
</svg>
```

### Using `graphics-symbol` on an inner element (correct)

Individual elements inside an SVG can carry a role like `graphics-symbol`. Each one needs its own accessible name.

```html
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <circle role="graphics-symbol" cx="50" cy="50" r="40" fill="yellow"
    aria-label="Warning indicator"></circle>
</svg>
```

### Decorative SVG (correct)

If the SVG is decorative, remove it from the accessibility tree with `aria-hidden="true"`. Do not assign a role of `img`, `graphics-document`, or `graphics-symbol`.

```html
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="100" height="100">
  <circle cx="50" cy="50" r="40" fill="yellow"></circle>
</svg>
```