WordPress alt text: good and bad examples
Alt text in WordPress is a short image description that a screen reader reads aloud and that helps Google understand the picture. You enter it in the Media Library or in the Image block. A good alt describes what you see in a few to a dozen words. An alt changed in the Library does not fix images already inserted into posts.
Author: The TellMyShop team. A guide for WordPress site and WooCommerce store owners: the cause, the manual fix and the same work in a chat conversation.
Last updated: · 6 min read
Who reads the alt and why
The alt has two readers. The first is a person who can't see the image: someone blind, partially sighted or on a slow connection where the image did not load. The screen reader reads the alt aloud instead of the image. Without an alt, they often hear the file name, such as “IMG_4471”, or nothing.
The second reader is Google. According to Google's image guidelines, the alt is one of the important sources of information about what an image shows, and it helps Google Images show it for the right queries. Google also notes that an alt stuffed with keywords does harm.
These two needs don't clash. An alt written for a person is usually good for Google too.
Good and bad alts, with examples
The examples come from a garden lighting shop. Each bad alt has a typical mistake found on WordPress sites.
| Image | Bad alt | Why it is bad | Good alt |
|---|---|---|---|
| Lantern on a terrace in the evening | IMG_4471 | the file name says nothing | Wrought iron lantern glowing on a wooden terrace in the evening |
| The same image | garden lanterns lanterns cheap shop lanterns | keyword stuffing | as above |
| Owner at a table with samples | image shows a woman | “image shows” is redundant, no content | The shop owner arranges lampshade samples on a workshop table |
| Product on a white background | product | too generic | Graphite LED garden wall light, side view |
| Ornamental line between sections | line | decorative graphic | empty alt |
| Chart in a guide | chart | hides the information | Chart: yearly power use of LED and halogen lamps, LED uses less |
More often than bad alts, you find no alts at all. If the site has hundreds of images without descriptions, start with those visible on pages with traffic: products, the services page, the most popular posts.
When the alt should stay empty
The advice “every image must have an alt” is a simplification. Graphics that only decorate, such as ornaments, backgrounds or an icon next to text that says the same thing, should have an empty alt. The screen reader then skips them and doesn't tire the listener with a description of a decorative line. That is what the W3C images tutorial recommends.
An empty alt is different from a missing alt. An empty one says “this is just decoration”. A missing one makes the reader guess, often by reading out the file name.
Where to enter alt text in WordPress
You have three places. Each works a little differently.
- Media Library. Media → Library, click the image and type the description in the Alternative Text field. WordPress saves the change by itself. This alt is suggested every time you insert the image and is usually used for the featured image (more on that in the guide to the featured image in WordPress).
- The Image block in the editor. Select the image in the post and enter the Alternative Text in the block settings panel. This change applies to that one post only. You will find a description of the block in the Image block documentation.
- WooCommerce product images. The main image and the product gallery come from the Media Library, so you enter the alt there. In a typical theme, the product page takes it straight from the Library.
The Title field in the Library is something other than the alt. The title mainly helps you find files and does not replace the description for a screen reader.
The trap: older posts don't see the new alt
This is where many people lose time. You fill in the alts in the Media Library, check an older post, and the page source still has an empty alt.
The reason is technical but simple. When you insert an image into a post in the block editor, WordPress copies the alt into the post content. From then on the post has its own copy. A later change in the Library fixes featured images and new insertions, but it does not change the copy in older posts.
With a few posts, open each one, select the image and fix the alt in the block. With many posts, start with those that get the most traffic.
How the chat fills in alts in batches
The “Image alt texts” task in the TellMyShop plugin for WordPress and WooCommerce starts with the Media Library. Your chat (Claude or ChatGPT) finds images without an alt there and suggests a description for each one based on the file name, the title and the page the image is attached to. For product images it takes the product data into account. When it can't tell what is in the image, it does not guess and adds the file to a list for you.
You: Fill in the missing image alts.
Your chat: The Media Library has 37 images without an alt. The first three, so you can approve the style:
I can't describe two files from their name and context, so I'm leaving them for you. Does the style work?
You: Yes, do the rest.
Your chat: Batch preview: 35 alts. I'll save it after your ‘yes’, and you can undo the whole batch from the change history.
Card status: waiting for your “yes”wrought-iron-lantern-02.jpg
old version: alt: none
new version: alt: Wrought iron lantern with its door open, front view
glass-lantern-terrace.jpg
old version: alt: none
new version: alt: Glass lantern with a candle on a terrace table
DSC_0193.jpg, attached to the product Small hanging lantern
old version: alt: none
new version: alt: Small hanging lantern in black on a chain
In the free TellMyShop Free the chat shows the list of images without an alt and suggested descriptions. Saving needs TellMyShop Pro. The chat then changes the alts in the Media Library, up to 50 files in one batch, after you approve the preview. The copies of alts in older posts are a separate change to the post content: the chat can fix them in selected posts, also with a “before → after” preview and the option to undo.
You will find the details and the sign-up list on the TellMyShop for WordPress and WooCommerce page, and prices in the pricing. Alts are one point of a broader site review, which we describe in the guide to a WordPress SEO audit.
A short cheat sheet
Describe what you see, the way you would describe the picture to someone over the phone. Skip “image shows”. Use a keyword only when it fits the picture. Give decorative graphics an empty alt. After changes in the Library, check older posts too. You will find more guides on the blog.
Questions and answers
Where do I enter alt text in WordPress?
In two places. In the Media Library, after clicking the image, in the Alternative Text field, and then the alt is suggested every time you insert the image. Or in the Image block in the editor, in the block settings panel, and then you change the alt in that one post only.
I changed the alt in the Media Library, but the post still has the old one. Why?
Because the block editor saves the alt in the post content at the moment you insert the image. A change in the Library works for featured images and new insertions, but it does not fix images inserted earlier. In older posts you have to change the alt in the Image block or in the post content.
Does every image need alt text?
Every image that conveys something, yes. Purely decorative graphics, such as ornamental lines or backgrounds, should have an empty alt so the screen reader skips them. An empty alt should be a deliberate decision for a specific graphic.
Should I put a keyword in the alt?
Only when it naturally describes what is in the picture. Google warns against stuffing keywords into alts. The alt “wrought iron garden lantern on a terrace” is better than “garden lanterns cheap lanterns shop”.
Will the chat recognise what is in the image by itself?
The chat writes the alt from the file name, the title and the page the image is attached to. When that data does not tell it what is in the image, it does not guess. Those files go on a list for you to describe.
WordPress is a trademark of the WordPress Foundation. WooCommerce is a trademark of Automattic Inc. Claude is a trademark of Anthropic PBC. ChatGPT and OpenAI are trademarks of OpenAI. TellMyShop is not affiliated with these companies.