Improving accessibility of image alternative text in 4.7

WordPress 4.7 includes a change to the way image alt attribute values are generated. Formerly, any time WordPress created the markup for an image with an empty alt value, it would attempt to use either the caption text or the image title—in that order—as a fallback value.

In 4.7, we have removed this fallback behavior.

To ensure your images having meaningful alternative text, you should makemake A collection of P2 blogs at, which are the home to a number of contributor groups, including core development (make/core, formerly "wpdevel"), the UI working group (make/ui), translators (make/polyglots), the theme reviewers (make/themes), resources for plugin authors (make/plugins), and the accessibility working group (make/accessibility). sure to set a value for alt text in your media library.

How removing fallbacks improves accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (

The intent of the fallbacks were to ensure each image included alternative text. In practice however, this fallback behavior often resulted in poor user experiences for people using screen readers. As counterintuitive as that may seem, let’s take a look at some common examples.

Consider a situation where we’ve uploaded an image named “edbc4ef7.jpg” without changing any additional information. WordPress will generate the image title from the file name as shown in the following screenshot of the insert media modal.

Attachment details for an image shown in the insert media modal.

Formerly, inserting this image in a post would result in HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. similar to this (simplified slightly for clarity):

<img src="" alt="edbc4ef7" width="700" height="467" />

A person using a screenreader on this page would end up hearing the file name read to them, which is not the most helpful experience, and can be quite frustrating when the file name is lengthy.

For another example, setting a caption value but no alternative text would result in markup that looks something like this:

<figure id="attachment_1741" style="width: 660px" class="wp-caption alignright">
    <img src="" alt="This is a caption." width="660" height="440">
    <figcaption class="wp-caption-text">This is a caption.</figcaption>

Notice that the alt value and the figcaption text are redundant? WebAIM describes two ways of presenting alternative text:

  • Within the alt attribute of the img element.
  • Within the context or surroundings of the image itself.

The same article goes on to explain that an alt attribute value may be omitted when an identical figcaption is present, to avoid redundancy; but best practice when using a figcaption is to provide a separate and different alt attribute to describe that image to users of screen readers.

In each case, omitting the alt attribute entirely may result in screen readers reading the file name from the src attribute, so WordPress includes an alt attribute with an empty value, i.e. alt="", whenever the alternative text hasn’t been explicitly set—a technique that is common when an image is decorative.

This change will not affect content already published, but will be the expected behavior for any new content published after upgrading to 4.7. For more background on this issue, see ticketticket Created for both bug reports and feature development on the bug tracker. #34635.

#4-7, #accessibility, #dev-notes, #media