Add Alternative Text to Images

Add a rich description to images and graphs to improve comprehension

Images can be a great way to engage your visitors and can help communicate complex ideas.

Image descriptions are often called "alternative descriptions", "alternative text", and "alt text". Image descriptions provide a text based, descriptive alternative to the image. For students with visual impairments, image descriptions that explain the content of an image are crucial for their learning. For all students, text descriptions can provide deeper context to aid their comprehension.

Ally checks for image descriptions anywhere there is an image. Ally checks images on a web page or in an attached file.

Ally ranks issues by severe, major, and minor.

  • Severe. These issues are the greatest risk to accessibility and require the most attention.
  • Major. These issues impact accessibility, and while not severe, require attention.
  • Minor. These issues should be considered for a better accessibility score.

Images missing alternative text is a major issue.

Use Ally to find images missing descriptions

Use Ally's accessibility report to discover and fix accessibility issues on your site. Use the link provided for the report and sign in. Open the report and look at the list of issues in the Accessibility Issues table.

The Accessibility Issues table is in both the Overview and Domain tabs. Start in the Domain tab to see issues specific to a domain. 

It's a major issue to have images without alternative text or descriptions. Use the Major tab in the Accessibility Issues table to view the list to major issues. Select the issues where images don't have descriptions.

If you start in the Overview tab, select the issue and then the domain with the issue.

Image description issues can start with Image, Document, or HTML in the list.

From the list of image descriptions issues in the domain, select the score indicator next to an item with the issue. The content editor feedback panel opens.

Preview the images without descriptions

Ally’s feedback panel shows you a preview of the content as well as detailed feedback and support to help you fix your accessibility issues. Use the preview to see the images without descriptions.

The preview highlights where specific accessibility issues can be found in the document. Highlights show every occurrence of one issue type at a time. For example, if your images are missing alternative descriptions, the highlights show you every place this specific issue occurs.

Preview tools

Use the preview tools to explore the issues in your document.

  • Move through the preview page by page.
  • See how many times a specific issue appears.
  • Jump between the issue highlights.
  • Hide or show the highlights.
  • Zoom the preview content in or out.
  • If the issue is in an attached document, download the original file.

Follow Ally's guided steps to add image descriptions

Ally assumes you have basic knowledge of HTML and how to use your Content Management System (CMS). To follow the guided steps you need to know how to edit a web page in the HTML or source code in your CMS.

Along with the preview, Ally gives you step-by-step guidance on how to fix the issue.  Ally organizes this feedback in a decision tree. All you need to do is read the directions and respond to the prompts. Learn what the issue is, why it matters, and how to correct it appropriately.

Select How to add descriptions to follow the guided steps.

Alternative Text on Images

Writing good descriptions

Follow these best practices to write good alternative text descriptions for your images:

  • Describe the image based on the page context. Convey the full meaning of the image.
  • Avoid saying "image of" or "picture of". Screen readers automatically announce images as images.
  • Be concise.
  • Write narratives for complex images like infographics. Put this narrative on the page immediately following the infographic. Include an anchor link at the top of the page to view the text alternative. See an example of an infographic with a text alternative.
  • Avoid images of text. If you can't avoid it, copy the text into the alternative description.
  • Say something new. Don't repeat alternative descriptions on the same page. Don't repeat what is already said on the page.
  • Identify images that don't represent relevant content as decorative.

What is a decorative image?

An image is decorative when it doesn't add to the information on the page. For example, art work used to separate topics or a photo of someone on the phone when discussing communication skills.

They are valuable in their visual appeal but may not need to be read by screen readers.

More on decorative images on the web accessibility initiative website

Why are alternative image descriptions important?

There are many reasons to use alternative descriptions with your images.

  • Alternative descriptions, or text, are in the WCAG 2.2 guidelines
  • Students can search for an image
  • Students with visual impairments have difficulty perceiving images
  • Student with a poor network connection may have difficulty perceiving images
  • Screen readers can't read images
  • Some students learn better from descriptions than images
  • Text scales better than most images when the screen or page is enlarged

Ways to add image descriptions on web pages

There is more than one way to add or edit image descriptions on your web pages.

  • HTML: Ally's guided steps walks you through how to find and edit image descriptions in HTML. Basically, find the web page with the image. Edit the page. Update the image HTML code to include an alt text attribute. Save the page.
  • Image settings: Most CMSs provide a way to edit alternative text in the image settings. Find the image on the web page or in the CMS file repository. Use the CMS tools to edit the image. Add the image description in the alternative text or alt text field. Save the image.

Visit w3schools to learn more about HTML and CSS

Why don't I see "img src" in my HTML?

The most common way to add images to a web page is with the img src HTML attribute. Img src is an HTML attribute that uses the URL of the image file to place the image on the web page. But every CMS is different. Your site may use different code or attributes. 

For example, in Drupal you might see something like this instead:

<drupal-entity data-embed-button="media_browser" data-entity-embed-display="view_mode:media.embedded" data-entity-type="media" data-entity-uuid="2961e3a2-8fbe-4e3f-baeb-953d69f70750"></drupal-entity>

Add alt text to the start of the attribute. For example,

<drupal-entity alt="add image description here" data-embed-button="media_browser" data-entity-embed-display="view_mode:media.embedded" data-entity-embed-display-settings="" data-entity-type="media" data-entity-uuid="2961e3a2-8fbe-4e3f-baeb-953d69f70750"></drupal-entity>

If you don't see img src in the HTML, try to use the CMS tools to edit the image settings. Find the image on the web page or in the CMS file repository. Use the CMS tools to open the image settings. Add the image description in the alternative text or alt text field. Save the image.

If you still don't know how to proceed, contact your web site administrator or developer. Ask them to show you how images are added to your web pages and how to add alternative text.