Alternative text for images in the content

The alternative text or “alt text” is used to provide an alternative to an image for users who can’t see it. Screen readers will announce that alternative text, so visitors that can not see the image will also know what it shows and won’t miss information. How do you add good alt text in your WordPress content?

How to implement and name images in development is addressed in the “Frontend code” section Images of this documentation.

The alternative text describes the purpose of an image

Describe (for non-visual readers) the contents and purpose of the image in your alternate text. That purpose may depend on the context in which an image is used.

Add alt text for images that contain text that is not contained in nearby text content.

Images with complex information, like infographics, should be described briefly in the alt text, and the information should be provided elsewhere on the page.

If an image is used as a link, use the link target as alt text. More about linking images in Images as links.

You can leave the alt text empty for images that are decorative and add no information to the content. Then a screen reader will skip that image and not announce it.

In the Web Accessibility Tutorials documentation of the W3C, the alt text Decision Tree tool is an almost comprehensive guide that describes how to provide alternative text in various situations.

Alt text in WordPress

In WordPress, you an add alt text for an image in the Media Library, in the Attachment Details panel for an image. This alt text will be used by default when embedding this image in content.

Screenshot of the attachment details of the WP A11y wapuu

When you add an image in the content using the Image Block, make sure the alt text still matches the purpose of the image as you are using it. The alt text for the image can be altered in the Block Settings and will only be used for this block.

Screenshot of the Image block settings for alt text

Overall benefits of using a proper alt text

People who can’t see your image can get equivalent information about it using their assistive technology, such as a screen reader or a Braille display.

The alt text also shows when the images are still loading, in the case of a slow internet connection.

The alt attribute helps with Search Engine Optimization. Google uses alt text along with computer vision algorithms and the contents of the page to understand the subject of the image.

Alt text also is useful for Answer Engine Optimisation (AEO), it provides essential information about the content in an image.

Examples

Don’t add “Image of”

When announcing an image, the screen reader announces the alt text and the fact that it is an image.

Don’t: Add the words “Image of”, Image of a nest of kittens..
Screen readers already add the information that it’s an image.

Do: Be brief and to the point.
Add the alt text A nest of kittens..

Explain the essence of an image

Think about what you want to tell with an image and capture that in the alt text.

Don’t: Describe everything that’s on the image, like the alt text:
“A photo of Jane, she is wearing her vintage dress by Dior, in her garden in full bloom, the sun is shining, she is smiling into the camera while holding a cup of coffee.”.

In a fashion blog, the relevant information might be “wearing a vintage dress by Dior”, on a gardening page the background garden might be most important, describe what’s important in the image.

Be to the point, like the alt text for a portrait:
“Jane, smiling into the camera.”.
The alt text for a photo of Jane, showing off her dress:
“Jane, in vintage Dior.”.
The alt text for a photo of Jane in her garden:
“Jane, in her garden in full bloom.”.

Resources

Related WCAG Success Criterion for alternative text for images

By giving a meaningful image the proper alternative text, you meet WCAG success criterion 1.1.1 Non-text Content (level A).

Other resources