Provide image descriptions

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 text, buttons, and other screen elements to audio and/or braille. If you are new to screen readers, I recommend watching a video to learn how it works.

Image descriptions are also beneficial to people who are colorblind, intellectually or cognitively disabled, and/or generally want more context about a photo.

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

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 black rectangles. Below are two h2 titles that say, "Wonderful title" and one has text below it that says, "And a wonderful subtitle too."

Alt text: Website with headers h1, h2, and h3 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="">

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 not for people who have the ability and energy to write descriptions themselves, or for those who have the financial means to pay someone to write the descriptions. They are community-driven efforts to make the practice of writing itself more accessible and available to disabled, neurodivergent, and chronically ill people.

Interesting further reading

How to Test This

Use automated tools such as Deque Axe, IBM Accessibility Assessment, and tota11y to check for the absence 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)