Images need alternative text

• Rule: axe/image-alt
• Checks: Images must have alternative text
• WCAG: 1.1.1
• Fix class: content: A fix needs authored text.

Who it affects

• People who use a screen reader or a braille display, most of them blind.

How to fix it

The image conveys information

Add an alt that gives, in a short phrase, the information the image adds to the page. Decide the words from the image’s purpose in its context; if you cannot tell what that is, ask the content’s owner rather than guess.

<img src="opening-hours.png" alt="Open Monday to Friday, 9 am to 5 pm">

The image is decorative or repeats text beside it

Set alt="", with nothing between the quotes, so assistive technology skips it.

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

The image is the only content of a link or button

Use the alt to name where the link goes or what the button does, not what the image shows.

<a href="/cart"><img src="cart.svg" alt="Cart"></a>

The image is a chart, diagram or map

Give it a short alt that says what it shows, and put the full information, such as the data, in text or a table next to it.

Fixes that fail

Using the file name or a generic word, such as alt="image" or alt="IMG_2041.jpg"

axe accepts any text, but these tell people nothing about the image.

Setting alt="" or role="presentation" on an image that conveys information

It silences the rule by declaring the image decorative, and screen reader users lose what it shows.

Starting the text with “Image of” or “Picture of”

Screen readers already announce an image as one, so the words only add noise.

In React

The part of the fix that differs in React, in its syntax. The rest of the guidance holds.

An image component takes alt from data that can be missing

Make alt a required prop and pass it straight to the <img>, writing alt="" out at each decorative use. React leaves out an attribute whose value is undefined or null, so a missing value leaves the image with no alt at all.

function Thumbnail({ src, alt }: { src: string; alt: string }) {
  return <img src={src} alt={alt} width={96} height={96} />;
}

Fixes that fail in React

Defaulting alt to an empty string, such as alt={photo.alt ?? ''}

Every image whose data lacks a text alternative is then marked decorative, so axe passes while screen reader users lose meaningful images. Get the missing text from the content’s owner instead.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.