# Images must have alternate text. Add an alt attribute to <img> elements. Decorative images may use an empty alt attribute (alt=""), role='none', or role='presentation'.

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

Every `<img>` element must have an `alt` attribute. When the `alt` attribute is missing entirely, screen readers fall back to reading the image's filename, which is often something like `IMG_20230415_092837.jpg` or `banner-final-v3.png`. This creates a confusing and unhelpful experience for people who rely on assistive technology to browse the web.

This rule applies to all `<img>` elements that are not programmatically hidden. Each image must either have a non-empty accessible name (through `alt`, `aria-label`, or `aria-labelledby`) or be explicitly marked as decorative using `alt=""`, `role="none"`, or `role="presentation"`.

## Who is affected

Screen reader users are the most directly affected. When an image lacks an `alt` attribute, the screen reader has no meaningful text to announce. Depending on the screen reader, it may read the file path, the URL, or nothing at all. None of these outcomes give the user the information the image was meant to convey.

Users of text-only browsers, users on slow connections who disable images, and users of braille displays also depend on text alternatives to understand image content.

## Related WCAG success criteria

This rule maps to [WCAG 2 Success Criterion 1.1.1: Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (Level A). SC 1.1.1 requires that all non-text content has a text alternative that serves an equivalent purpose, unless the image is purely decorative. Because this is a Level A requirement, it is the minimum baseline for accessibility conformance.

## How to fix it

The fix depends on the purpose of the image.

### Informative images

If the image conveys information or has a function, write a concise `alt` value that describes the content or purpose. Good alt text answers the question: "If I couldn't see this image, what would I need to know?"

- Keep it short. One or two sentences at most.
- Describe the content or function, not the appearance, unless appearance is the point.
- Do not start with "Image of" or "Picture of." Screen readers already announce the element as an image.

### Decorative images

If the image is purely visual (a spacer, a decorative border, an icon next to text that already says the same thing), mark it as decorative so screen readers skip it. You can do this with:

- `alt=""` (an empty alt attribute, not a missing one)
- `role="none"`
- `role="presentation"`

An empty `alt` attribute and a missing `alt` attribute are different things. `alt=""` tells assistive technology to ignore the image. A missing `alt` attribute tells it nothing, so the screen reader guesses.

### Images inside links or buttons

When an image is inside a `<a>` or `<button>` element that already contains visible text, the image is usually decorative in that context. Use `alt=""` so the screen reader does not announce the image redundantly. If the image adds information that the surrounding text does not cover, write alt text that complements (not duplicates) the existing text.

When an image is the only content inside a link or button, the `alt` text becomes the accessible name for that interactive element. In this case, the alt text should describe the link's destination or the button's action, not the image itself.

## Accessibility support notes

Some browsers do not fully treat `alt=""` as equivalent to `role="presentation"`. They may still include the image in the accessibility tree with a role of `img` or `graphic`. In practice, most mainstream screen readers handle `alt=""` correctly, but behavior can vary across browser and assistive technology combinations.

If an image with `alt=""` is also focusable (for example, because it has a `tabindex`), the handling is inconsistent across browsers. Avoid making decorative images focusable.

## Examples

### Missing alt attribute

This `<img>` element has no `alt` attribute. A screen reader may announce the filename.

```html
<img src="w3c-logo.png">
```

### Empty alt attribute on an informative image

This image conveys meaning, but the alt text is empty. Screen readers will skip it entirely, and users will miss the information.

```html
<img src="chart-q4-revenue.png" alt="">
```

### Correct alt text for an informative image

The `alt` attribute describes what the image communicates.

```html
<img src="w3c-logo.png" alt="W3C logo">
```

### Correct handling of a decorative image

This decorative flourish adds no information. An empty `alt` attribute tells screen readers to ignore it.

```html
<img src="decorative-divider.png" alt="">
```

Using `role="none"` achieves the same result:

```html
<img src="decorative-divider.png" role="none">
```

### Image as the only content in a link

When the image is the sole content of a link, its alt text should describe the link destination.

```html
<a href="/home">
  <img src="home-icon.png" alt="Home">
</a>
```

### Decorative image inside a link with text

The link already has visible text, so the image is decorative in this context.

```html
<a href="/profile">
  <img src="profile-icon.png" alt="">
  My Profile
</a>
```

### Using aria-label as an alternative

The `aria-label` attribute can provide an accessible name instead of `alt`, though `alt` is the standard approach for `<img>` elements.

```html
<img src="w3c-logo.png" aria-label="W3C logo">
```

### Using aria-labelledby

The `aria-labelledby` attribute references another element's text as the accessible name.

```html
<span id="logo-label" hidden>W3C logo</span>
<img src="w3c-logo.png" aria-labelledby="logo-label">
```