What is alternative text?

After using create_template() to create a skeleton of your document, you will see chunks containing fig-alt: in the figures.qmd files, like this:

The fig-alt parameter in this chunk signifies that this is where you should add a description of your figure that can be read aloud by the screen reader. This description, otherwise known as alternative text (alt text for short) should answer this essential question:

What is this image conveying?

How do I write alt text?

While tempting, tools like AI cannot be used to easily answer this question. Additionally, one should not use the caption as the alt text. Here are four essential ingredients for well-written alt text, as described by Drs. Silvia Canelón and Liz Hare in their talk, “Revealing Room for Improvement in Accessibility within a Social Media Data Visualization Learning Community”¹:

1. Type of data visualization (e.g., scatterplot, line graph, box-and-whisker plot)
2. Axis variables
3. Range of the data
4. The relationship between the variables shown (i.e., what the figure is conveying)

Dr. Hare stresses the importance of ingredient #4 by explaining,

Don’t waste my time with 1-3 if you aren’t going to include 4. While some automatic alt text processes mine some of this information, I don’t want to spend time building a mental model of the graph if I can’t find out what the graph says.²

Both presentations are great resources for learning about alt text and will help you as you craft your own alt text!

Example of alt text

Here is an example of a figure with a caption and alt text. The caption is shown directly below the figure and is written in the chunk’s options (fig.cap=""). The alt text is also included in the chunk’s options (fig.alt="") but is not shown unless the webpage is inspected with Developer Tools or it’s extracted with a screen reader.

library(ggplot2)

orange <- as.data.frame(Orange)
orange <- orange |>
  dplyr::mutate(Tree = base::factor(Tree,
    levels = c(1, 2, 3, 4, 5)
  )) |>
  dplyr::rename(
    Age = age,
    Circumference = circumference
  )

ggplot2::ggplot(
  data = orange,
  aes(
    x = Age,
    y = Circumference,
    color = Tree
  )
) +
  ggplot2::geom_line(size = 1) +
  ggplot2::geom_point(size = 2) +
  ggplot2::scale_color_viridis_d() +
  ggplot2::xlim(0, NA) +
  ggplot2::ylim(0, NA) +
  ggplot2::theme_bw() +
  labs(
    x = "Age (days since 1968/12/31)",
    y = "Orange Tree Circumference (mm)"
  )

Tree circumference and age for 5 orange trees.

The figure’s alt text is written as such:

A line graph showing how tree circumference increases with age for a set of 5 orange trees. Age, shown on the x axis, is measured in days since 1968/12/31 and spans from 118-1582 days. Circumference, shown on the y axis, spans from 30-214 mm. All trees showed an increasing trend of trunk circumference with age, with each tree starting with a circumference of 30-33 mm at age 0 and ending with a circumference of 140-216 mm at age 1582. At age 1582, the tree with the largest circumference was tree 4, followed by trees 2, 5, 1, and 3.

More resources

Looking for more resources for writing alt text? Check out the NOAA Library’s website for creating accessible documents.