An image with an image description in the caption below
Image description: An abstract graphic illustration with an image description in the caption below. The description says, โ€œYellow square with black squiggles, purple circle, red square, and black outlined triangle against a light orange background."

This page is in progress -

If you would like to contribute or make a case to prioritize this page, please fill out the form below.

Why This is Important

An image description describes the essential information in an image. It is primarily for Blind and visually impaired people to access visuals.

Blind and visually impaired people use screen readers to interact with websites and apps. A screen reader is a type of assistive tech that converts things on screen to audio and/or braille. It's important that things are understandable and interactive to screen readers.

Keyboard accessibility is essential for people who do not use a computer mouse (which might be because they have unpredictable or very specific movement due to a motor disability). Many Blind and visually impaired people also use keyboard interactions in order to use their screen reader.

Error support is accessible to people with a diversity of disabilities. A cognitive disability might affect how a person perceives and understands things. A physical disability might lead to unpredictable movement. Other factors such as environment, stress, and multi-tasking may also lead to errors.

In order to be accessible, gestures and interactions must account for people with physical and motor disabilities, who might have unpredictable or very specific movement.

Image descriptions are essential for Blind and visually impaired people to access images. They are also beneficial to people who are colorblind, people with cognitive or intellectual disabilities, people who want more context about an image, etc.

This references WCAG criterion 1.1.1 Non-Text Content (Level A).

Level AAA compliance is considered more difficult to meet because it requires more resources to fulfill. It also might encompass conflicting access needs (meaning what is accessible to some might be inaccessible to others). Use your best judgment of your target audience and your team's capabilities to determine if this is a pragmatic goal to reach.

How to Implement This

Where to add the image description

Many people have suggested to me that the best place for the image description is actually in the caption that is also visible to sighted people. Why? Because:

  • It's available to screen magnifier users
  • It's available to sighted people who may need or benefit from the description
  • It's available to people who want to share the image, so they can copy/paste the description

Typically, it is recommended to add the description in the alt attribute of the image, such as in below:

<img src="kittens.jpg" alt="3 small brown kittens taking a nap in a basket">

My current understanding of a more accessible experience is to add the complete description in the visible caption and add an abbreviated note in the alt attribute.

For example, here's what I'd recommend for the following image:

Website with headers h1, h2, and h3 labeled

Image description:
A website titled, "Amazing blog," which is labeled h1. The navigation, labeled main-nav, shows 4 tabs. Below are two h2 titles that say, "Wonderful title." The first heading has text below that says, "And a wonderful subtitle too."

Alt text: Website with headers and main-nav labeled

If the image is being uploaded to a social media platform, there is usually an alt text field that you can add it to. Here are tutorials for instagram, twitter, facebook, and medium.

Decorative images

WCAG notes that decorative images do not require alt text because they do not add information to the page. In this case, the alt attribute should be written as:

<img src="pattern.png" alt="">


What makes an image decorative might depend on your audience. Some people prefer a lot of visual detail. Others do not want image descriptions unless the image itself conveys meaning. The direction you go will depend on your capacity and your target audience.

How to write an image description

Here's an image description writing guide that I created. I am constantly evolving it based on feedback, so feel free to leave comments. Here is a Brazilian Portuguese translation of my article: Como descrever uma imagem

Other guides for writing image descriptions:

Community support for image descriptions

Depending on your spoons or disability, writing image descriptions may not be feasible. There are community groups available to provide more collective access, where you can request other people to write it for you.

Please note: These groups are community-driven efforts to make the practice of writing itself more accessible and available to disabled, neurodivergent, and chronically ill people. For those who have the ability, energy, and/or financial resources to write descriptions, it's recommended that they are in a supportive role.

Interesting further reading

How to Test This

Manual Test
Semi-Automated Test
Automated Test

Use automated tools such as Deque Axe, IBM Accessibility Assessment, and tota11y to check for the presence of image alt text.

Keep in mind that these automated tools only test for the existence of alt text, and not their quality or how descriptive they are. In an interesting Carnegie Mellon study of image description on twitter it describes on page 6 a rating of the quality of descriptions, from "irrelevant" to "great: almost everything described."


No credits yet. But this could be you!

Corrections to decorative alt text by Cam Beaudoin, The A11y Coder

Contribute and Give Feedback

If you would like to provide feedback or contribute content on this resource, please fill out the form below.

Thank you, your submission has been received!
Oops! Something went wrong while submitting the form. Please check your internet connection and try again.

If you continue to encounter issues, please reach out to alexyingchen(at)