Mastering the art of `alt` text for images
Tags: html, a11y, images
Published: 2021-05-19 13:40:54

Writing the `alt` text for images is probably one of the most difficult tasks for web developers. The _HTML Living Standard_, the version last updated on 18 May 2021, provides a lengthy guidance in its section 4.8.4.4, with as many as 15 subsections within it ([WHATWG 2021, §4.8.4.4](https://html.spec.whatwg.org/multipage/images.html#alt)). [WebAIM (2019)](https://webaim.org/techniques/alttext/) also provides a very lengthy guidance, with the following introductory sentences:

> Adding alternative text for images is the first principle of web accessibility. It is also one of the most difficult to properly implement.

I'd always wanted to figure out the proper way of writing `alt ` text, but didn't have time to do so. Today I decided to crack it. 

Spending the whole day, I learned tons of things, especially from the lengthy [HTML Living Standard §4.8.4.4](https://html.spec.whatwg.org/multipage/images.html#alt), which is actually very well-written with lots of examples clearly demonstrating each rule.

But it's very long. Not everyone has time to read it through. 

After digesting what I have learned, I realize we can summarize the best practices on `alt` text with 10 lessons, 4 of them derived from a simple example of the flowchart image, 4 more on the `alt` text itself, and the last 2 for when we don't need the `alt` attribute altogether.

## Lessons from a flowchart

The most illuminating example from the [HTML Living Standard §4.8.4.4](https://html.spec.whatwg.org/multipage/images.html#alt) is how to mark up a flowchart like this one:![The Network
passes data to the Input Stream Preprocessor, which passes it to the
Tokenizer, which passes it to the Tree Construction stage. From there,
data goes to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to the
Tokenizer.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/07byupisl9sprkb96gbn.png)

Source: [HTML Living Standard §4.8.4.4.3](https://html.spec.whatwg.org/multipage/images.html#a-phrase-or-paragraph-with-an-alternative-graphical-representation:-charts,-diagrams,-graphs,-maps,-illustrations)

From this chart, we can learn four lessons about what `alt` text really is about.

### Lesson 1: Use `alt=""` if there is a text equivalent nearby.

If this flowchart is accompanied with its text equivalent, the `alt` text should be an empty string:

```html
<p>
  The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction stage. From there, data goes to both the DOM and to Script Execution. Script Execution is linked to the DOM, and, using document.write(), passes data to the Tokenizer.
</p>
<p>
  <img 
    src="images/parsing-model-overview.svg" 
    alt=""
  />
</p>
```
Source: [HTML Living Standard §4.8.4.4.6](https://html.spec.whatwg.org/multipage/images.html#a-graphical-representation-of-some-of-the-surrounding-text)

The same principle applies when an icon image is used next to its text equivalent ([HTML Living Standard §4.8.4.4.4](https://html.spec.whatwg.org/multipage/images.html#a-short-phrase-or-label-with-an-alternative-graphical-representation:-icons,-logos)).

### Lesson 2: Describe the image in detail if there is no text equivalent.

If there is no text equivalent near this flowchart, however, the `alt` text should explain the flowchart:

```html
<p>
  In the common case, the data handled by the tokenization stage
comes from the network, but it can also come from script.
</p>
<p>
  <img 
    src="images/parsing-model-overview.svg" 
    alt="The Network passes data to the Input Stream Preprocessor, which passes it to the Tokenizer, which passes it to the Tree Construction stage. From there, data goes to both the DOM and to Script Execution. Script Execution is linked to the DOM, and, using document.write(), passes data to the Tokenizer."
  />
</p>
```
Source: [HTML Living Standard §4.8.4.4.3](https://html.spec.whatwg.org/multipage/images.html#a-phrase-or-paragraph-with-an-alternative-graphical-representation:-charts,-diagrams,-graphs,-maps,-illustrations)

The same principle applies when an icon is used with no text equivalent next to it ([HTML Living Standard §4.8.4.4.4](https://html.spec.whatwg.org/multipage/images.html#a-short-phrase-or-label-with-an-alternative-graphical-representation:-icons,-logos)). 

It also applies to the images as content (e.g. works of visual art), rather than as a graphical representation of text content (like a flowchart). See [HTML Living Standard §4.8.4.4.11](https://html.spec.whatwg.org/multipage/images.html#a-key-part-of-the-content) for some examples.

### Lesson 3: If the image is wrapped in `<figure>`, repeat the text equivalent of the image as the `alt` text.

This is the most surprising lesson to me: if the flowchart is wrapped in the `<figure>` element, even with its text equivalent around, the `alt` text SHOULD explain the flowchart:

```html
<p>
  The Network passes data to the Input Stream Preprocessor, which
passes it to the Tokenizer, which passes it to the Tree Construction stage. From there, data goes to both the DOM and to Script Execution. Script Execution is linked to the DOM, and, using document.write(), passes data to the Tokenizer.
</p>
<figure>
  <img 
    src="images/parsing-model-overview.svg" 
    alt="The Network leads to the Input Stream Preprocessor, which leads to the Tokenizer, which leads to the Tree Construction stage. The Tree Construction stage leads to two items. The first is Script Execution, which leads via document.write() back to the Tokenizer. The second item from which Tree Construction leads is the DOM. The DOM is related to the Script Execution."
  />
  <figcaption>
    Flowchart representation of the parsing model.
  </figcaption>
</figure>
```
Source: [HTML Living Standard §4.8.4.4.6](https://html.spec.whatwg.org/multipage/images.html#a-graphical-representation-of-some-of-the-surrounding-text)

The reason is, if I understand correctly, that the `<figure>` element must be self-contained: it should be understood if seen separately from the article that refers to it.

> The `figure` element [represents](https://html.spec.whatwg.org/multipage/dom.html#represents) some [flow content](https://html.spec.whatwg.org/multipage/dom.html#flow-content-2), optionally with a caption, that is self-contained (like a complete sentence) ([HTML Living Standard §4.4.12](https://html.spec.whatwg.org/multipage/grouping-content.html#the-figure-element), with links added as in the source).

### Lesson 4: The `alt` text is NOT a figure caption.

This last example HTML code also tells another surprising fact to me: the `alt` text is different from the figure caption, i.e., the text content of the `<figcaption>` element.

Somehow I wrongly believed that we wouldn't need the `alt` text if there was a figure caption provided with `<figcaption>`, based on the logic that the `alt` text could be empty if the surrounding text describes the image (Lesson 1 above). 

No, that's not true. If there is an empty `alt` text with the figure caption, it'll be like a caption attached to a pitch-black rectangle. This will be utterly puzzling to screen reader users. See [O'Hara (2019)](https://www.scottohara.me/blog/2019/01/21/how-do-you-figure.html) for more detail.

## How to write `alt` text

It's not enough for us to understand when to provide non-empty `alt` text. We need to know how to write `alt` text in such situations. There are four lessons for it.

### Lesson 5: Don't start with "Image of", "Photo of" or "Picture of".

Screen readers will read out there is an `img` element on a web page, before starting to read the `alt` text. Consequently, screen reader users already know it is an image of something. So the phrase like "Photo of" or "Picture of" is redundant, unless it is important to know the image is a photograph rather than an illustration, for example ([WebAIM 2019](https://webaim.org/techniques/alttext/)). This lesson appears to be mentioned in every single article on `alt` text (e.g., [Robertson 2013](https://www.a11yproject.com/posts/2013-01-14-alt-text/)), but I didn't know...

For a similar reason, the logo image doesn't need a word *logo* in its `alt` text. Just use the name of a company or any other organization/brand that the logo represents.

> The `alt` attribute must *not* contain text like  the word "logo", as it is not the fact that it is a logo that is being conveyed, it's the entity itself. ([HTML Living Standard §4.8.4.4.4](https://html.spec.whatwg.org/multipage/images.html#a-short-phrase-or-label-with-an-alternative-graphical-representation:-icons,-logos))

This is something I didn't know either...

### Lesson 6: Imagine you're explaining a webpage to someone on the phone.

This rule of thumb is written in [HTML Living Standard §4.8.4.4.1](https://html.spec.whatwg.org/multipage/images.html#general-guidelines), and I find it the most helpful. Imagining you're talking to someone is the best way to write up text. Otherwise you'll end up writing something difficult to understand.

Consequently, reading the `alt` text should flow naturally from the previous paragraph to the following paragraph, as the following pair of good and bad examples demonstrates:

```html
<!-- A good example -->
<p>
 You are standing in an open field west of a house.
 <img 
   src="house.jpeg" 
   alt="The house is white, with a boarded front door."
 />
 There is a small mailbox here.
</p>
```

```html
<!-- A bad example -->
<p>
 You are standing in an open field west of a house.
 <img
   src="house.jpeg"
   alt="A white house, with a boarded front door."
  />
  There is a small mailbox here.
</p>
```
Source: [HTML Living Standard §4.8.4.4.3](https://html.spec.whatwg.org/multipage/images.html#a-phrase-or-paragraph-with-an-alternative-graphical-representation:-charts,-diagrams,-graphs,-maps,-illustrations)

### Lesson 7: Don’t insert line breaks

[Faulkner (2015)](https://www.tpgi.com/short-note-on-coding-alt-text/) reports that screen readers will read the `alt` text in a weird manner if there is a line break within it.

Indeed, [Prettier](https://prettier.io/) won't insert any line break inside the `alt` attribute value even though it does for text within `<p>` elements etc. 

### Lesson 8: For image links, write as if it were text links.

This is a piece of advice coming from Google ([Google Developers 2021](https://developers.google.com/search/docs/beginner/seo-starter-guide?hl=en&visit_id=637570241373552632-1180617535&rd=1#use-html-images)). Rather than describing the image itself, we should describe what the linked page is about.

Writing link text is the whole another piece of art for UI designers. See, for example, [Moran (2019)](https://www.nngroup.com/articles/better-link-labels/) from Nielsen Norman Group.

## When no `alt` text is needed

Finally, we need to know when we actually don't need to write up the `alt` text. We've already seen one situation where we can go with `alt=""` (see Lesson 1 above, if you forget it by now).

To understand when to use `alt=""`, we need to understand what it semantically means. Here's our 9th lesson: 

### Lesson 9: Screen readers may ignore `<img>` elements with `alt=""`

In a section describing the `alt` attribute, [MDN (2021)](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attributes) states:

> Setting this attribute to an empty string (`alt=""`) indicates that this image is *not* a key part of the content (it’s decoration or a tracking pixel), and that non-visual browsers may omit it from [rendering](https://developer.mozilla.org/en-US/docs/Glossary/Rendering_engine). [The link added as in the source.]

This is why we use `alt=""` if there is a text equivalent of the image nearby on the web page. Another situation for `alt=""` is when the image is purely decorative. That is exactly when we want screen readers to ignore the image. 

This 9th lesson has an important consequence regarding the claim put forth in many articles on `alt` text that I've seen. They insist that we should always give the `alt` attribute to the `<img>` elements. Our 10th lesson contradicts with their claim for a good reason:

### Lesson 10: Omit `alt` attribute when images are auto-generated without alt text.

A careful reading of [HTML Living Standard §4.8.4.4.11](https://html.spec.whatwg.org/multipage/images.html#a-key-part-of-the-content) reveals one valid case for omitting the `alt` attribute:

> In some unfortunate cases, there might be no alternative text available at all, either    because the image is obtained in some automated fashion without any associated alternative text (e.g. a Webcam), or because the page is being generated by a script using user-provided images where the user did not provide suitable or usable alternative text (e.g. photograph sharing sites), or because the author does not themself know what the images represent (e.g. a blind photographer sharing an image on their blog).

In these cases, if we use `alt=""`, then screen readers may ignore these images even though they are not purely decorative (that is our Lesson 9). To avoid this effect, we can drop `alt` attribute from the `<img>` element.

However, we should instead provide an image caption with `figcaption` or `title` attribute to the `<img>` element ([HTML Living Standard §4.8.4.4.11](https://html.spec.whatwg.org/multipage/images.html#a-key-part-of-the-content)). 

Once we know all this, the following cryptic description of what the lack of `alt` attribute implies will actually make sense:

> The absence of the `alt` attribute indicates that the image is a key part of the content but that a textual replacement for the image was not available when the image was generated. ([HTML Living Standard §4.8.3](https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element))

This description is often cited in articles on `alt` text. When I first read this, I was like "What the hell are you talking about?" Now I understand what it means, or more accurately, why they define the absence of `alt` this way.

---

## Now it's time to remember all these 10 lessons

I believe the above 10 lessons cover pretty much all the usual cases of using `<img>` elements. For minor cases, here's the list of references:

- Image maps: [WebAim (2019)](https://webaim.org/techniques/alttext/#imagemaps) 
- Multiple image files as one image: [WebAIM (2019)](https://webaim.org/techniques/alttext/#slices) and HTML Living Standard [§4.8.4.4.9](https://html.spec.whatwg.org/multipage/images.html#a-group-of-images-that-form-a-single-larger-picture-with-no-links) and [§4.8.4.4.10](https://html.spec.whatwg.org/multipage/images.html#a-group-of-images-that-form-a-single-larger-picture-with-links).

There are many web articles on `alt` text out there, but I typically  find their advice difficult to remember. There are so many cases to consider, and the article authors throw at us all these cases without clearly explaining the underlying principles. One such example is W3C's page entitled "An `alt` Decision Tree" ([W3C 2019](https://www.w3.org/WAI/tutorials/images/decision-tree/)), which I find is confusing rather than helpful.

This article aims to be easy to remember. The flowchart example can remind us of the first 4 lessons. Plus, 4 lessons about `alt` text itself and 2 lessons about when we don’t need `alt` text. I think it’s well-structured enough to remember easily or at least more easily.

If you still forget what to do with `alt` text, come back to this article. I will do myself when that happens. :-)

## Postscript (added on 30 Aug, 2021)

The above 10 rules will also apply to those "decorative" images that are often recommended to have `alt=""`, because they do convey information: an atmosphere of a webpage. See [Watson (2011)](https://tink.uk/text-descriptions-emotion-rich-images/) and [Archibald (2021)](https://jakearchibald.com/2021/great-alt-text/). 

See also [Bailey (2021)](https://www.smashingmagazine.com/2021/06/img-alt-attribute-alternate-description-decorative/), who says the technique of `alt=""` was historically relevant but is rarely appropriate today, partly because the lack of alt text can be "confusing for someone with low vision who is using a screen reader" (on this point, see [Roselli 2017](https://adrianroselli.com/2017/02/not-all-screen-reader-users-are-blind.html)).

## References

Archibald, Jake (2021) ["Writing great alt text: Emotion matters"](https://jakearchibald.com/2021/great-alt-text/), _Jake Archibald wrote..._, Aug 4, 2021. 

Bailey, Eric (2021) ["Your Image Is Probably Not Decorative"](https://www.smashingmagazine.com/2021/06/img-alt-attribute-alternate-description-decorative/), _Smashing Magazine_, Jun 17, 2021.

Roselli, Adrian (2017) ["Not All Screen Reader Users Are Blind"](https://adrianroselli.com/2017/02/not-all-screen-reader-users-are-blind.html), _adrianroselli.com_, Feb 15, 2017.

Watson, Léonie (2011) ["Text descriptions and emotion rich images"](https://tink.uk/text-descriptions-emotion-rich-images/), _Tink_, Jun 3, 2011.