Skip to main content Skip to secondary navigation

Alternative text (alt text) for images and other media

Main content start

When writing alternative text, the first question you should ask yourself is, "Should I write anything at all?"

What is alternative text?

Alternative text (also known as "alt text") provides a textual alternative for media items such as images, audio, and video, and for visually complex content such as tables, charts, and graphs. So, if an image does not load, for example, this is the text that will be displayed in its place. Additionally, this is the text that will be provided to assistive technologies, making it a vital part of accessibility for the site.  

What should I write for alt text?

If your media item contains pictures of text or other important information, you'll want use alt text to describe what you see and explain its importance. The alt text is a substitute for what you see in the image.

If an image is decorative, that is, the image doesn't add new or pertinent information, you probably won't want alt text. That is, when the page renders, the alt attribute will render as alt="" . When adding an image or other media to the media library on your Stanford site, that's the equivalent of leaving the Alternative text field blank. 

People in images

When uploading profile photos and other images of people, if names are provided it's preferred to put those names in the caption to make that information available to all users. Otherwise, if alt text is needed, use the person's name in the alt text. When describing people, unless it’s explicitly provided, avoid mentioning gender, age, and ethnicity.

Image gallery

Because images in an image gallery are the purpose of the image gallery, all gallery images require descriptions as captions and/or alt text. 

Describe complex images 

If you have complex images like infographics, graphs, charts, diagrams, illustrations, and maps you must provide a complete text equivalent. Here are some considerations:

  1. The text for alt attribute must be kept short (less than 150 characters) and simply describe the image
  2. Consider using the caption of the image to summarize the image message. This helps all audiences. 
  3. If there is text in an image, that text also needs to be available for screen readers.
  4. If the image has is more information than can be captured with the alt attribute and caption, provide a longer description elsewhere, and link to it in the caption.

Alt text for complex images

When writing text for the alt attribute of a complex image, consider the form to describe the image:

alt="[type of image] of [data] that shows [the message to convey]".

For example:

alt="Chart of student grade averages for 2020-2023 that shows a decrease over time: 2020 95%, 2021 90%, 2022 85%, 2023 80%".

Use captions

If the description for the alt attribute is long, say over 120 characters, or the information would be useful for all audiences, use a caption and if necessary provide a longer description elsewhere. Then shorten the text for the alt attribute to:

alt="[type of image] of [data] 

In the previous example, the text for the alt attribute could be:

alt="Chart of student grade averages for 2020-2023. 2020 95%, 2021 90%, 2022 85%, 2023 80%"

The image caption could convey the image message:

Student grade averages for 2020-2023 show a decrease over time.

Describe complex images elsewhere

Complex images with more data or other information may require a multi-part text alternative. For more on this, see Add transcripts or longer descriptions

Resources for complex images

Add transcripts with audio files

If you embed audio files on your site, you are required to include a transcript. Including transcripts along with your embed in the body of a page is a great way of providing content for everyone. This is also fabulous for SEO purposes, as all this keyword-rich content is now searchable, and for people for whom English is not their primary language.

For instructions on adding transcripts, see Add transcripts or longer descriptions.

Review these tips from the Office of Digital Accessibility on using captions and transcripts before posting media to your website.

To share or not to share?

Just as an image or other media on your Stanford site can be shared in several places on your site, the alt text is also shared.

Before adding existing media such as an image to a page, you’ll want to make sure the alt text matches its context. If the existing alt text does not match the image context, you can override the alt text for a particular display.

To see the alt text for an image or other media item

Hover over the image so that you see the media toolbar.

  • Click on the eye icon
  • This will bring up a field where you can override the alt text for that image
  • Click the green checkmark to save.


Seeing the alt text through the Media Library

You can also check alt text via the Media Library

  1. In the admin menu go to All Content > All Media > Media Library and search for your image
  2. Click on the pencil icon to bring up the edit page for the image
    Screenshot illustrating  Alternative (alt) text for Media

On the edit page for the media item you can change the Name and Alternative text for the image. If it is already in use, a Drupal message will give the number of times the image is in use.

Screenshot illustrating Alternative (alt) text for Media

Related Topics

desk step with different typography elements
Learn about the most flexible tool you have with the Text Area Paragraph.