Warninga11y.image-alt

Images have no alt text

Why it matters

A screen reader can't see an image: it reads the alt attribute instead. When there is no alt at all it falls back on whatever it can find, which is usually the file name: "I M G underscore 4 0 3 2 dot J P G". The same text is what shows when the image fails to load, and what a search engine takes the image to be of.

An empty alt="" is not a mistake. It is how you say "this is decoration, skip it", and it is right for flourishes, spacers and an icon that sits beside a word saying the same thing. What is flagged here is the attribute being absent, which says nothing either way.

Source: WCAG 2.2, 1.1.1 Non-text Content (Level A); W3C's alt decision tree.

How to fix it

Say what the image shows, as you would to someone on the phone, and leave out "image of":

<img src="/cakes/three-tier.jpg" alt="Three-tier wedding cake with sugar peonies">

For decoration, keep the attribute and leave it empty:

<img src="/flourish.svg" alt="">

In WordPress it is the Alternative Text box in the media library.

Examples

These are the rule's own test pages, and what it says about each. They are run on every change to the rule book.

<img src="/cakes/three-tier.jpg">

Warning1 image has no alt attribute, so a screen reader reads out the file name or nothing: img.

fail-no-alt
<img src="/flourish.svg" alt="">

PassedEvery image has an alt attribute (1 image).

pass-decoration
<img src="/cakes/three-tier.jpg" alt="Three-tier wedding cake with sugar peonies">

PassedEvery image has an alt attribute (1 image).

pass-described