How to write alternative text

A picture is worth a thousand words, so how do we write alternative text?

We can’t use text to replicate the same value of what a well-sighted user gains from an image. We can at least make alternative text as useful as possible.

The WAI’s alt Decision Tree and WCAG’s techniques give guidance on the types of images, along with an understanding of if and when to add alternative text. They also provide some examples, but not much help with the how.

Alternative text should convey important, contextual and imaginable information.

Important information

For most websites, a user isn’t interested in reading an entire paragraph on the details of an image.

We should include the parts that make up an image without including every detail, as that overloads the user with information.


Photo of a painting depicting a self-portrait of Vincent van Gogh displayed in a beautifully lit art gallery

Photo by Dan V on Unsplash.

A photo of a French painting using rhythmic brushstrokes in striking colours depicts a self-portrait of Vincent van Gogh portraying himself as a fashionably dressed Parisian in Paris, in 1887. The painting, hanging on a wall, has been placed in a gold frame with a caption label describing the painting in detail on the left side, mounted on the wall. The wall is dark blue, there is a soft circular light surrounding the painting and a harsher point light aimed from above which creates a shadow below the painting.

Including every detail may be necessary depending on the context of the website.

For most, this is far too much and reading a description with every detail like this can be frustrating.

Here is the description distilled to the key information:

Photo of a painting depicting a self-portrait of Vincent van Gogh

All alternative text should include this key important information from an image.

Context is key

Depending on where your image is being used can determine what should be included in alternative text.

Images on websites often have a reason or a purpose for being there. Try to include what the image is conveying.

Understand what role the image has in the context of the website. Add what is happening in the image and if there are emotions, a tone or a story surrounding it.


A moody greyscale professional photo of person in a suit and tie holding a feather-like grass against their face

Photo by Ruslan Lissitsa on Unsplash.

Let’s imagine this image on a website selling cars to set the tone. Based on the image, you’d expect them to be luxurious cars.

Applying this context gave further meaning on top of the important information which you would want to include in the alternative text.

This is contextual information.

Now let’s imagine the image on a Diversity & Inclusion page for a fashion brand’s corporate website.

The context has shifted and its purpose is now more specifically targeting the brand’s audience and to show the company’s diverse culture. The tone is still important but the main focus is now on the person in the image and their attributes.

Notice how context can shift an image’s alternative description. It’s not always about describing the image, it’s also about what the image means in the context of its placement.


Finding the important and contextual information only takes you so far. If you only follow those steps, the text will often end up being cold or blunt.

I recommend adding some flourish or detail to help someone depict the image in their mind.

You might include what people are doing in the image, how vivid colours are, the smile on a person’s face, or the feeling an image provides.

No one wants to read a boring description of an image. Make alternative text useful, but also make it imaginable.


  • What is the purpose of this image?
  • What is the important information?
  • Does this information matter?
  • What is contextual information?
  • Does this information change anything?
  • Can I shorten this without losing information?
  • Can I reduce the complexity of text without losing information?