Mastering the art of `alt` text for images

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). WebAIM (2019) 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, 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 is how to mark up a flowchart like this one:

Source: HTML Living Standard §4.8.4.4.3

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:

<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

The same principle applies when an icon image is used next to its text equivalent (HTML Living Standard §4.8.4.4.4).

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:

<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

The same principle applies when an icon is used with no text equivalent next to it (HTML Living Standard §4.8.4.4.4).

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 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:

<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

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 some flow content, optionally with a caption, that is self-contained (like a complete sentence) (HTML Living Standard §4.4.12, 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) 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). This lesson appears to be mentioned in every single article on alt text (e.g., Robertson 2013), 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)

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, 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:

<!-- 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>

<!-- 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

Lesson 7: Don’t insert line breaks

Faulkner (2015) reports that screen readers will read the alt text in a weird manner if there is a line break within it.

Indeed, Prettier 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). 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) 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) 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. [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 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).

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)

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)
• Multiple image files as one image: WebAIM (2019) and HTML Living Standard §4.8.4.4.9 and §4.8.4.4.10.

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), 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) and Archibald (2021).

See also Bailey (2021), 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).

References

Archibald, Jake (2021) "Writing great alt text: Emotion matters", Jake Archibald wrote..., Aug 4, 2021.

Bailey, Eric (2021) "Your Image Is Probably Not Decorative", Smashing Magazine, Jun 17, 2021.

Roselli, Adrian (2017) "Not All Screen Reader Users Are Blind", adrianroselli.com, Feb 15, 2017.

Watson, Léonie (2011) "Text descriptions and emotion rich images", Tink, Jun 3, 2011.

Comments

[GrahamTheDev]

I am enjoying this deep dive into HTML elements and attributes (although it is scattered across other series....it is a shame they don't let you add articles to two different series on here so I can keep track of them!)

I have almost finished my <abbr> piece I promised you a couple of weeks back, I would expect that to land next week some time.

We could have a good discussion on point 10, the problem here is if you have information for a caption, you can add an alt attribute so this guidance doesn't work in the real world, this is often an issue with WCAG. This one is particularly tricky as if it is user generated content do you add alt="user generated content" or alt="no alt text given" or just leave it as an empty attribute as it adds no value to a screen reader user? What makes it worse is that some older / obscure screen readers will read the file name and path if an alt attribute is omitted and you really don't want that!

The point on imagining you are describing the image on the phone is a great one! I am stealing that one 😁

The other thing to consider is that when writing your alt text, context matters an awful lot.

If you are writing an article about cheese then a picture of a cheese board with cheese, ham etc. should have a different alt attribute text than if the article was about planning a dinner party (first alt text would focus more on the cheese types on the board accompanied by ham, bread etc. The second would describe it as a cheese board with finger food including cheese, ham, bread etc.) Probably not my best example but you get the idea!

The final consideration is alt attributes should be short and succinct. If you feel there is need for added information you may want to use aria-describedby to add much more info for example or another suitable method.

Anyway, finally realised I hadn't followed you yet so have a ❤🦄 and a follow from me, I look forward to the next instalment!

[Masa Kudamatsu]

Thanks a lot for your comments! I want to incorporate your comments into the article, but I haven't had time...

I've just written another article, this time on landmark roles and their consequences on the use of <nav>. Let me know what you think. ;-)

[Sharang Ahirekar]

References are very helpful, Thank you for such a great article!