Someone ran an accessibility or SEO check on your site and it came back with a long list: “image missing alt attribute”, page after page. Or a visitor who uses a screen reader mentioned that your services page reads out as “image, image, image”. Either way, you now need to add alt text in WordPress, and you want to know where the box is and what on earth to type into it.
The box is in two places, and which one you use matters more than most people expect. What to type is a small skill, and an easy one to pick up once you have seen a few examples.
What alt text actually does
Alternative text is a short written stand-in for an image. Screen readers read it aloud to people who cannot see the picture. Browsers show it when an image fails to load. Search engines use it, along with the surrounding text, to understand what the image shows. It is not visible on the page in normal use, which is why it is so often forgotten.
It is not a caption. A caption is printed under the image for everyone. Alt text is for those who are not seeing the image at all. The difference between alt, caption, title and description is set out in our post on image captions, titles and alt text; here we stay with alt.
Where to add alt text in WordPress
There are two boxes, and they are not linked to each other once an image has been placed.
In the Image block (for one page)
- Open the page or post and click the image.
- In the settings sidebar on the right, under the block’s settings, find Alternative text. If the sidebar is closed, click the settings icon at the top right.
- Type the text and save or update the page.
This text is stored in the page content itself. It affects only this one use of the image.
In the Media Library (for future uses)
- Go to Media → Library and click the image.
- In the Attachment details panel, fill in Alternative Text. It saves as you click away.
The Library value is copied into a block at the moment you insert the image. It is also what most themes use for the featured image of a post, and what many galleries and widgets pick up.
The catch: fixing the Library does not fix old pages
If you add alt text in the Library today, images already sitting in pages keep whatever alt text they had when they were placed, often nothing. To fix an existing page, you have to edit the Image block on that page too. That surprises nearly everyone, and it explains why a site can look “done” in the Library while a checker still reports missing alt text.
A sensible routine: write the alt text in the Library when you upload, so every new use starts with something good, and check the block’s box when you place the image, adjusting the wording if this page uses the picture for a different purpose.
Writing good image alt text
Ask one question: if I read this page aloud to someone over the phone, what would I say when I reached the picture? That sentence is usually your alt text.
- Say what matters about it here. A photo of your staff on the About page might be “The four-person team outside the office”. The same photo used on a careers page might be better as “Our team at the office, where new staff would work”.
- Be specific but brief. One sentence, often less. There is no exact character limit, but long paragraphs are tiring to listen to.
- Skip “image of” and “picture of”. Screen readers already announce that it is an image.
- Include any words in the image. If a graphic says “Free delivery in Kolkata this week”, the alt text must say that too, or the message is lost.
- For a logo, use the company name, and if the logo links to the home page, something like “Acme Tiles, home page”.
- For a linked image, describe where the link goes: “View our bathroom renovation work”, not “Bathroom photo”.
- Do not stuff keywords. “Best plumber Kolkata plumber services plumbing” helps no human and does not help search either.
Some before-and-after examples
| Image | Weak alt text | Better alt text |
|---|---|---|
| Product photo in a shop | product1 | Brass table lamp with a cream linen shade |
| Before-and-after of a job | before after | Kitchen wall before and after retiling, cracked tiles on the left, new white tiles on the right |
| Chart of opening hours | hours | Open Monday to Saturday, 10am to 7pm; closed Sunday |
| Owner’s portrait | image of person | The founder at her pottery wheel in the studio |
Decorative images: leave the box empty
Not every image needs a description. A background texture, a divider line, or a stock photo of a handshake that adds nothing to the text is decorative. For those, leave Alternative text blank. WordPress then outputs an empty alt, which tells screen readers to skip the image rather than read out its file name.
The judgement call is whether a visitor who cannot see the image misses anything. If the text beside it already says everything, the image is decorative. If someone would lose information, it needs a description. When an image sits right next to a heading that names it, avoid repeating the heading word for word in the alt text; the visitor would hear it twice.
Fixing images you already have
On a small site, the most reliable method is page by page:
- List your most important pages: home, services, about, contact, and the posts that bring the most visitors.
- Open each in the editor and click every image. Check the Alternative text box.
- Write or fix it, then update the page.
- While you are in each image, open the Library entry too and fill its alt text, so it is right the next time the image is used.
Plugins and some SEO tools offer to fill missing alt text automatically, often from the file name or the page title. Treat that as a placeholder at best. “IMG 4471” or the same page title on every image is no better than nothing for a screen reader user. Some newer tools write descriptions with AI; those can be a useful first draft, but read each one, because they describe what is visible rather than why it is on the page, and they get details wrong.
Images in places other than the Image block need their own check. Gallery images take their alt text from the Library at insertion. Images placed in page builders like Elementor usually have their own alt setting in the widget, or pull it from the Library. A Cover block treats its picture as a background, so make sure the text placed over it carries the message on its own. Our website accessibility checklist covers the other things worth checking while you are going through pages.
Mistakes to avoid
- Putting the description in the Title field instead of Alternative text. They are different fields.
- Writing the same alt text for every photo in a gallery.
- Describing a decorative image in great detail, which only adds noise.
- Assuming the Library fix covers the pages. It does not, as explained above.
Alt text is one of four text fields every upload carries, and our overview of the WordPress Media Library and image settings shows how it connects to uploads and image sizes. Settings, menus, plugins and the other parts of the site have their own sections in our WordPress help guide.
Frequently asked questions
Does alt text help my images appear in Google Images?
It can help, because Google uses alt text along with the file name, nearby text and the page itself to understand an image. It is not a switch that makes images rank. Write it for people first; an accurate description that suits the page is also the kind of text that helps search engines.
Should every image in a gallery have different alt text?
Ideally yes, because each photo usually shows something different, such as a different room or product. Write each one in the Library before adding the images to the gallery, since the gallery takes the alt text from there. If several photos are almost identical, describe what differs between them, like the angle or the finish.
What happens if I leave alt text empty on an important image?
WordPress outputs an empty alt, so screen readers treat the picture as decorative and skip it. Visitors who rely on them miss whatever the image showed, and accessibility checkers may not even flag it, because an empty alt is technically valid. That is why it is worth deciding image by image rather than leaving the box blank by habit.
Can I add alt text in other languages on a multilingual site?
Yes, but how depends on the translation plugin. Most multilingual plugins let you translate the alt text along with the page, or keep a separate Library entry per language. Check that the translated page shows alt text in the right language, because an English description on a Bengali or German page is confusing for screen reader users.
Going through every page of an older site is slow, careful work. If you would like someone to do the alt text along with the other accessibility fixes, it can be handed to our team that handles WordPress support work. You would still want to read the wording on your key pages, since you know your business best.
Next in this series: How to Crop an Image in WordPress and Resize It
