Did an “Image Missing Alternative Text” or “Image Empty Alternative Text” error appear in an Accessibility Checker audit of one of your WordPress posts or pages? Read on below for an explanation of this error, how it impacts your website’s accessibility, and how to fix it.
Table of Contents
- About the Missing Alternative Text Error
- Impact on Accessibility
- How to Fix Image Missing or Empty Alternative Text Errors
- What to do (in short)
- How to find images with missing or empty alt text on your WordPress post or page
- Adding alternative text in the media library vs in a post or page editor
- How to write good alternative text
About the Missing Alternative Text Error
What is alternative text?
Alternative text is a short phrase that is included in HTML image tags and is used to describe the image being displayed on the web page.
Image alternative text, colloquially referred to as “alt text,” is visible to sighted users only if the image fails to load. Otherwise, it can be used to relay the contents of an image to a blind or visually impaired individual using a screen reader or to a search engine that is trying to understand the contents of a web page for search engine optimization purposes.
How is alternative text added to images in WordPress?
Alternative text is added to an image tag by placing it inside the alt attribute, for example:
<img src="https://equalizedigital.com/wp-content/uploads/2020/11/corgi-laptop-1024x1024.jpg" alt="cute corgi laying in front of open laptop on bed and looking happily at camera">
The code example above shows the web address from which the following picture is displayed and the alt text that we have used to describe the image, which is “cute corgi laying in front of open laptop on bed and looking happily at camera”.
In WordPress, alternative text is commonly added without having to touch any code and can be edited via the media library, the relevant image block in the Gutenberg page editor, or via a visual page builder. How you can add and edit alt text in your website varies based upon your specific WordPress setup.
How is missing alternative text different from empty alternative text?
Missing alternative text means that your image does not have an
alt attribute in the image tag at all. This is an example of an image in code that has a missing
Empty alternative text means that you have an alt attribute with no text within it, I.e., your image tag has
alt="" in it. Here is an example of an image in code with empty alternative text:
<img src="/dog.jpg" alt="">
How does Accessibility Checker test for missing alternative text?
While auditing your page or post content, Accessibility Checker will identify all images (<img>) and <input> tags with a type of image and check to see if they have an alt attribute and confirm that the following is true:
- the image does not have role=”presentation”,
- the image does not have an aria-hidden attribute,
- the image is not a 1×1 spacer pixel,
- the image is not generated by Google ads code,
- if the image is in a link (
<a>tag) it does not have a valid aria-label, or
- that the image is not contained within a valid caption.
If none of the above are true and there is an alt tag but it contains no text, an Image Empty Alternative text error will be flagged.
If there is no alt attribute at all and none of the above apply, then it will result in an Image Missing Alternative Text error.
Impact on Accessibility
Why is alternative text important?
Alternative text, when correctly added to an image, conveys meaning about what the image is to people who cannot see it. Generally, in order to convey meaning and improve the user experience on the site, alternative text should be an accurate description of the image or the purpose of the image in the case of a linked icon. Only images that are purely decorative in purpose and add no value to the content on the page should have an empty alt attribute. Ni images should have a missing alt attribute.
Missing alt tags and accessibility
If an alt tag is missing completely from an image, some screen readers will attempt to compensate for the missing alternative text by reading the file name of the image. As you can imagine, it is, in many cases, insufficient to rely on the file name to provide information about the image because many content managers do not upload images with meaningful file names to their website. It is not uncommon to see websites with image file names like “sidebar.png,” “img_54321.jpg,” or “shutterstock_123456789.jpg.” These file names provide no information to users of assistive technology describing the image.
If the screen reader does not read the file name, then it may just announce “image” with no other information at all, which is equally confusing for blind and visually impaired users.
Empty alt tags and accessibility
Generally, if the alternative text is empty, screen readers will skip over it, not relaying that an image is present to blind and visually impaired users. Empty alternative text is correct for decorative images so that assistive technology users are only presented with the information that matters as they move through the page, not slowed down by announcements of “border” or “decorative accent.”
People who are blind are not able to quickly skim a web page when it loads. They need to have their screen reader read them out all of the information on the page, and any extraneous information can increase the time it takes for them to find what they’re looking for and slow them down. It is important to only present information to screen readers that is a vital part of the meaningful content on the page.
Decorative vs. non-decorative images
As mentioned above, decorative images, like borders, small color swatches, or image backgrounds, should have an empty alt tag in order to be properly accessible. Alternative text is not necessary and it is correct to leave the alt attribute empty on decorative images so that screen readers will skip over the image and not announce its presence.
Below is a screenshot that shows two different images on a page about ice cream sundaes. There is a heading, “Ice Cream Sundaes,” followed by an image that looks like triangle bunting running across the page. Below the bunting image is a photograph of an ice cream sundae with hot fudge, sprinkles, and a cherry on top.
In this example, we have drawn an arrow pointing to the bunting graphic to highlight that the bunting graphic is decorative.
Decorative images don’t convey meaning or add real value to someone’s understanding of the content on a page, like the other images on the page do. In the example above, the photograph of the sundae helps to illustrate what an ice cream sundae is for those who don’t know. If this were a restaurant website, the sundae might help customers know what to expect if ordering the sundae off the menu or seeing the image might aid in their purchase decision. In this way, the photograph adds value to the page that the bunting image does not.
If the two images, above, were on your website, you would want to enter alt text for the sundae photograph but not for the bunting image and would want to ensure that the bunting image has an empty
alt tag present.
If you’re not sure if your image is decorative and needs alt text or not, you may find this alt decision tree helpful.
Relevant WCAG 2.1 Success Criteria
All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, with a few exceptions.
How to Fix Image Missing or Empty Alternative Text Errors
What to do (in short)
To fix an Image Missing Alternative Text error, you will need to add an alt tag to the image with appropriate text describing the purpose of the image in the page. If the image is decorative, the alt attribute can be empty, but it still needs to be present.
To fix or resolve an Image Empty Alternative Text error, you need to all appropriate alternative text to describe the image’s purpose. If the image is decorative, then you would leave the alternative text blank and “Ignore” the error.
How to find images with missing or empty alt text on your WordPress post or page
For any pages or posts that have an Image Missing Alternative Text or an Image Empty Alternative text error in the WordPress editor, you can open the details tab in the Accessibility Checker meta box, then expand the applicable error to see a list of the images (in code) that caused the error to be flagged.
Fixing empty alternative text
This screenshot shows two examples of images with empty alternative text that have been flagged in Accessibility Checker.
The code for the images in this example is:
<img src="https://demosite.equalizedigital.com/wp-content/uploads/2020/11/border_example-1-e1605038372679-1024x133.png" alt="" class="wp-image-156"/> <img src="https://demosite.equalizedigital.com/wp-content/uploads/2020/11/Sundae-day-1024x1024.jpg" alt="" class="wp-image-154"/>
These two images are the same images that were shown above in our decorative vs non-decorative image example – the image of the bunting border and the ice cream sundae graphic. If this were your website and you were not sure which images were being flagged, you could look at the image URL for a hint. As shown here, we have named our image files appropriately before upload, sot it helps us to see that the first image is the board and the second is the photograph of the sundae.
If the file names for your images are not this obvious, then you may need to check for alt text on every image in the WordPress editor or can right click on the images in your post and click “open in a new tab” to see the file name for each image.
Once you know which images need to be fixed, the appropriate fixes for the flagged errors on these two images is:
- Add a descriptive alt text to the ice cream photograph in the WordPress editor (described below).
- Ignore the error on the border graphic because it is decorative and it is a “false positive” that is not really an error as-is. See How to Ignore for more information.
Generally, if the image is added to a post or page with an image block in the Gutenberg block editor or with the “Add Media” button you can simply click on the image to add alt text within the editor.
Fixing missing alternative text
This example shows one image that has been flagged as missing alternative text in accessibility checker.
The code for the image in this example is:
If this were your website, you would want to add alternative text that describes the content of each image, assuming it is not a decorative image.
Missing alternative text is generally more complicated to fix in WordPress than adding alt text to images with alt tags that are present but empty. In many cases, alt attributes may be missing from images on the front end of your website even if those image have alternative text defined within the media library.
When the image has alternative text defined within WordPress but your website is not outputting the alt on the front end of your website, then it is likely that your theme or a plugin requires a code fix to ensure that alt text is included in the image tag. We frequently see this sort of problem in WordPress themes (equally free and custom coded) that don’t use default WordPress functions to output images and are outputting them only with their URL, in which case the developer has to manually include the alt text as well.
Here are some additional resources if the alt text is missing from your images despite being defined in WordPress’ editor:
- What to do if There are Accessibility Errors in Your Theme
- What to do if a Plugin You’re Using has Accessibility Errors
Adding alternative text in the media library vs in a post or page editor
There are two ways to add alternative text to your images in WordPress. You can add them to images within the media library or can add them directly in the post or page where they are embedded, as shown in the image in the preceding “Fixing empty alternative text” section.
Add contextual alt text on your page/post edit screen
If you add alt text within a post or page edit screen, that alternative text will not be saved in the media library and will only be visible on that particular post or page. If you insert the image again on a different page, you will need to add alt text to the image again on the second page where it is being used. The reason for this is that good alternative text is supposed to be contextual and provide meaning to enhance the content on the page. In that way, the same image used on multiple pages may not always have the same alternative text.
Here is an example of an image that might have different alternative text depending upon the context on the page:
If you were to use this photograph on your business’ about page alongside text that describes your business’ location, you might write alt text like:
Sunny day on First Street with XYZ Co. building on the left and city skyscrapers in the background.
In this usage, you would have alt text that helps blind or visually impaired customers to picture your company’s location, mentioning that it’s in an urban environment by noting the presence of skyscrapers. You might mention that it’s a sunny day to help frame the photograph in a positive light. There would be no need to mention that no people or cars are present in the photograph.
In contrast, you could use this same image on a post about COVID-19’s impact on businesses and would want to convey the empty nature of the city. You also might be less apt to discuss the sunlight or anything that would frame the nature of the photograph in a more positive light. In this case, the alt text might be:
Eerily empty buildings, sidewalks, and streets as downtown businesses lockdown.
Notice for this same image the alternative text can be dramatically different depending upon how it is being used. For this reason, it is preferable to write the alternative text for your image on the page(s) where they are being used so that you can ensure that the alt text is meaningful within the other content on the page.
WebAIM has additional examples about context within alt text.
Add missing alt text to many images quickly in the Media Library
If you have many images that are missing alternative text, the fastest way to add alternative text to your images quickly is to add the text within the WordPress Media Library.
We have audited websites where no one was thinking about accessibility or search engine optimization and there are literally thousands of images on the site without alternative text. If your website has many, many images that are missing alternative text, then the fastest way to add alternative text to all of your images quickly is to add the text in the attachment details popup that appears after clicking on an image thumbnail in the media library.
As shown above, when viewing the attachment details, you can add type alternative text in a box to the right of the image, then you can use the left and right arrows at the top right of the popup to move to the next image. This will allow you to add alternative text as quickly as possible to a large number of images.
Alt text added here should be more general, rather than contextual since you may not know how the image is being used on the website, but should accurately describe the contents of the photograph or graphic. If alternative text is not set within the post or page, in most instances WordPress will display the alternative text saved in the media library. As a result, this is the best option for initially improving accessibility and you can always go back and make the alt text more contextual at a later date.
How to write good alternative text
In addition to providing contextual information about the image as it relates to the content on the page, here are some other guidelines for ensuring that your alternative text is useful:
- Do not include phrases like “image of” or “photo of” – screen readers will announce that it is an image without you writing that.
- Do not use the alt attribute as a place to stuff keywords purely intended for search engine optimization. Make sure your alt text accurately describes with is in the image.
- Do not write overly long alt text that is more than a few words or a short sentence. Anything more than 100 characters will flag a long alt text error.
- Do not repeat information contained in a caption or nearby text.
Visit our Low-Quality Alternative Text article for more tips on writing meaningful alt text.