Alt text

​​Alt text is read aloud to screen reader users, often people who are blind or have low vision, so that they understand what is in an image they cannot see. Alt text may also be shown to sighted users in place of an image that is unable to load. It is commonly called alternative text or an image description.

Technical implementation (img vs. svg) and fallbacks

For img tags

Alt text is supplied via the alt attribute on img tags. An example of this is <img alt="alt text goes here" src="example.png" />.

Every img tag should have the alt attribute. Failure to explicitly set this value may lead to the image file name being read out loud to screen reader users, which is often an unhelpful user experience.

If we explicitly set alt="", then the image will be skipped by screen readers. If an image is purely decorative and/or repeated for dramatic effect (for example, you have a series of snowflake images scattered across a winter-themed page), then it is best practice to use alt="". You should have something like <img alt="" src="purely-decorative.png" />.

Note: If your img tag's src is the path to an SVG, then you should add role="img" to the img tag. It may seem redundant, but this helps screen readers treat the SVG correctly when reading alt text. So we should have <img alt="alt text goes here" src="example.svg" role="img" />.

For svg tags

svg tags do not have the alt attribute, but we can still provide alt text for SVGs.

We recommend using whichever of the following two methods is most appropriate for your use case.

Method 1: Set aria-hidden="true" on svg and add alt text elsewhere (preferred method)

Note: We use a span to house the alt text in the example below, but you may find another element type, such as a table, is better suited to describe certain svg contents. In the past, The Post has used an sr-only table as an alternative to a map svg to share county-level election results with screen reader users.

For our WPDS Icon component, we use the following steps:

1. Add aria-hidden="true" to the svg tag so that it is skipped by screen readers.
2. Add a span next to the svg (as an immediate sibling element) and apply the sr-only class or Visually Hidden wrapper so the span is readable only by screen readers.
3. Add the alt text for the svg into the newly added span element. Since this alt text is not in an img element, screen readers will not be told that the text is describing an image by default. This is a case where you should explicitly add "image" (or in the example below, "icon") to the alt text.

Below is an example of how this works. Inspect the icon with the Chrome developer tools to view the HTML and CSS. Or, better yet, test it out with the screen reader of your choice.

Method 2: Use aria-labelledby with title tag and aria-describedby with desc tag (a lightweight solution for when Method 1 isn't doable)

1. Add a title tag as the first child of the svg tag (as shown in the example below) to provide a brief description of the image. The title may also be viewable to sighted users who hover over the svg with a mouse.
2. If the image cannot be described with a brief (approximately one sentence) title, then add a desc tag below the title tag to provide more details. As an example, the desc for an SVG graphic may list out specific details from the graphic whereas the title briefly summarizes the graphic's appearance and purpose. Individual rects, circles and other visual elements within an svg tag can have their own titles and descs, but we recommend just one title and one desc at the root level — as described above — for a more straightforward user experience.
3. Give the title and desc tags unique id attribute values. Then, in the svg tag, set aria-labelledby="id of title tag goes here" and aria-describedby="id of desc tag goes here".
4. Since we do not apply aria-hidden="true" to the svg tag in this method, we must apply aria-hidden="true" to each text tag within the svg. Otherwise the title and desc tags may not be read correctly. Note that the "visible text" element in the example below is not read by a screen reader but is mentioned as part of the alt text in the desc tag.

Select "Show code" below to view our implementation. This is a model you can follow for your own SVGs.

a11y-101.com demonstrates other ways to label the heart svg above, including their shortcomings. Carie Fisher, a Senior Accessibility Consultant and Trainer at Deque Systems, also performed a study comparing different alt text placements for SVGs.

In summary, there is not a perfect solution to alt text for SVGs. We recommend Method 1 above as a means of getting around this.

Defining fallback values for alt text

If an image is important to understanding an article or product, then fallbacks for alt text should not be used. The field should be required in those cases.

However, there are some circumstances where fallbacks for alt text can be helpful, if done correctly.

We have an engineering blog post with more context on fallbacks for alt text and how they can affect user experience.

The best fallback in most cases: alt=""

alt="" is usually the best fallback for alt text.

Alt text needs to be thoughtfully written, and other fallbacks will likely be unhelpful and potentially even confusing or misleading for users. Anywhere an unknown image may be missing alt text (for example, old content with many non-essential images is being ported to a new platform), it is better to use alt="" than to risk getting something wrong with another fallback.

Do not use a generic value like "Image" or "Image without alt text" as a fallback. This text is useless to screen readers and clutters the user experience.

When other fallbacks can be used

If you have some basic context on what an image contents, such as a name or caption field, then you may be tempted to use this as fallback alt text. However, this can lead to a redundant user experience if the name and caption are already rendered elsewhere on the page where the image appears (for example, a profile picture is rendered right next to the person's name). As shown below, captions serve a different purpose than alt text anyway.

An example of where non-empty fallback alt text could be helpful: Imagine you have a live-updating feed of recent purchases from vending machines and are rendering them as their product images from the front of the vending machine. Sighted users can read the labels in the product images, so there aren't text labels in the page HTML. The database you are working with has a required name field for each vending machine item that matches what is written in the product image, so you can use that name field as fallback alt text when more descriptive alt text has not yet been written.

In cases like these where fallback alt text other than alt="" is actually helpful, this is often an indicator of other issues. For example, it would be better to render the name as text for all users in the situation above than to rely on them reading it from images.

Captions vs. alt text explained

Alt text is not the same as a caption.

A caption is generally adding context to an image, whereas alt text is describing what the image contains for those who can’t see it.

Consider The Post's caption for the below image: "This image released by NASA on July 12 was captured by the James Webb Space Telescope. (AP)"

The caption is effective. It adds useful context for readers: when the image was released, who released it and how it was taken. The caption also credits AP (The Associated Press) for providing the image.

NASA wrote the following alt text for the image above:

"The image is divided horizontally by an undulating line between a cloudscape forming a nebula along the bottom portion and a comparatively clear upper portion. Speckled across both portions is a starfield, showing innumerable stars of many sizes. The smallest of these are small, distant, and faint points of light. The largest of these appear larger, closer, brighter, and more fully resolved with 8-point diffraction spikes. The upper portion of the image is blueish, and has wispy translucent cloud-like streaks rising from the nebula below. The orangish cloudy formation in the bottom half varies in density and ranges from translucent to opaque. The stars vary in color, the majority of which have a blue or orange hue. The cloud-like structure of the nebula contains ridges, peaks, and valleys — an appearance very similar to a mountain range. Three long diffraction spikes from the top right edge of the image suggest the presence of a large star just out of view."

Most images should not have alt text as long or complex as the example above. However, this example shows the purpose of alt text.

When we use an image in our work, it is our job to describe in text what the image contains — in the way most contextually relevant to where it appears — for blind and low-vision users. In this case, NASA wanted to capture the detail of the image because that was its relevance to the story being told: the power of the new telescope and the level of detail it unlocked.

Below is guidance on how to approach alt text in different scenarios that are common in media.

How to write useful alt text

Alt text for images of text

All of the text from an image you want your users to see should also be included in the alt text for that image so blind and low-vision users can hear it.

For instance, an image of a headline should have the headline also added in the alt text field. You may add additional context, such as "Screenshot of a Washington Post headline that says, 'Eagles lose Super Bowl 38-35'" where "Eagles lose Super Bowl 38-35" is the exact headline from the screenshot.

Below is an example from The Washington Post Twitter account.

Alt text for data visualizations

Data visualization alt text should focus on the visualization type, the type of data shown and the reason for including the visualization.

Read more detailed guidance on alt text for data visualizations from Amy Ceval, co-founder of the Data Visualization Society.

Below is an example from The Washington Post Twitter account.

Alt text for other images

1. Describe the type of image, if relevant. Don't use generic phrases like "Picture of" or "Image of" because screen reader users already know when they are hearing alt text for an image. If the image has a specific type (illustration, graphic, headshot, etc.), then it is probably relevant to note that, as done in the example below.
2. Be concise. Alt text doesn't need to describe every tiny detail in an image, just the relevant parts for the overall meaning. Typical alt text is no more than a few sentences. If the image is complex, this may be longer, but try to keep it as short as possible while including all necessary details.
3. Never assume race, gender, etc. If known, use these and other identifiers when relevant to the image or context in which the image is used. Note that the subject of the image may have their own preferences on how they are identified for the purposes of a story or other content.
4. Avoid including your opinion on the image. Alt text should be an objective description. Words like "pretty" or "scary" are generally not useful. Focus on what is happening in the image.
5. Write in plain language so that the alt text's meaning is clear. Avoid complicated words and sentence structures. Avoid jargon and idioms. We have more guidance on plain language.

Below is an example from The Washington Post Twitter account.

Things to exclude: hyperlinks and emojis

Hyperlinks

Links are not clickable when used in alt text. A screen reader user may hear each character in the link read out one by one and will be unable to click the link anyway. Include links in the text surrounding the image instead of in the alt text, and make sure to follow our hyperlink text guidelines for that.

Don't just take our word for it; try it yourself. Use a screen reader to listen to a hyperlink in alt text. You will probably hear something like "h-t-t-p-colon-slash-slash" and so on. It is a bad user experience.

Emojis

Alt text is for people who cannot see the image. Emojis and symbols often have confusing or unintended text when read by a screen reader, so they should be avoided entirely.

Similarly, avoid emoticons like :) in your alt text and elsewhere. Screen readers may not recognize them and may instead read them as punctuation.

How to handle punctuation and hashtags

Punctuation

Listen to your alt text using a screen reader to understand how punctuation affects the way it is read aloud.

Deque provides a guide to special characters for screen readers, which gives context on how some punctuation is read by screen readers.

But online guides are not a substitute for manual testing. Guides become outdated quickly as screen readers evolve and change.

Hashtags and CamelCase

Social media hashtags are a form of hyperlink and thus won't be clickable in alt text.

If a hashtag is essential to the alt text because it is the name of a movement or effort, for instance, then it should be included in the alt text with CamelCase formatting. CamelCase involves capitalizing the first letter of each word in a multiple-word hashtag. This allows screen readers to distinguish words in a hashtag and increases legibility for everyone.

For example, use #TheWashingtonPost instead of #thewashingtonpost.

Capitalize the letters in acronyms and initials as well.

For example, use #WPMedia instead of #Wpmedia.

SEO considerations

SEO is not the purpose of alt text. We write our alt text to make content more accessible to real users.

Google warns us not to stuff keywords into alt text: "Avoid filling alt attributes with keywords (also known as keyword stuffing) as it results in a negative user experience and may cause your site to be seen as spam." So, trying to abuse the alt text field for SEO can actually end up hurting your SEO.

Consider the potential SEO benefits of alt text to be a positive side effect of making our content more accessible.