Good image alt text tells someone what they need to know from an image when they cannot see it. It does not have to describe every visible detail, and not every image needs a written description. On a WordPress website, the right choice depends on what the image does on that particular page.
For most site owners, the quickest test is this: if the image disappeared, would a visitor miss information or an action? If yes, write a short alternative that supplies what is missing. If no, and the image is there only for decoration, mark it as decorative. The W3C’s image alt-text decision tree is a useful reference when the answer is less obvious.
What should alt text say?
Describe the image’s purpose in context, rather than producing an inventory of everything in the frame. Imagine a service page with a photograph showing a technician fitting a replacement window. If that photograph demonstrates the work described, “Technician fitting a replacement window in a customer’s home” is more useful than “Man with tools”. If the same photograph is merely a visual backdrop beside a full description of the work, it may not need spoken alt text at all.
Keep it concise, but include a detail if that detail matters to the page. A product photograph might need the product type, colour or distinguishing feature. A screenshot in a tutorial should identify the control or setting the reader is meant to find, not just say “WordPress dashboard”. Usually there is no need to begin with “Image of” or “Photo of”: the image is already presented as an image.
Context also explains why copying one description to every use of an image can go wrong. The same photograph might introduce a team member on an About page but act as decoration on a general contact page. Decide what a reader needs from each placement.
When should you leave alt text empty?
Leave alt text empty when an image adds no information beyond the surrounding words: a decorative flourish, a stock photograph used only for atmosphere, or an illustration whose meaning is already fully expressed next to it. The W3C recommends an empty alt attribute for these images so screen readers can skip them. That is different from omitting the alt attribute altogether, which can cause an unhelpful filename to be announced. See the W3C’s decorative-image examples if you are unsure.
Do not mark an image as decorative simply because it is attractive. If a before-and-after photograph demonstrates a change, a diagram explains a process, or an image contains information that is missing from the copy, visitors need access to that information too.
Three situations that need extra thought
Image links and buttons
If an image is the only content of a link or button, its alternative should explain what happens when it is used. “Download the site-care guide” is more helpful than “Book cover” for an image-only download link. If readable text in the same link already states the destination, repeating it in the image alt text may create unnecessary duplication. The W3C’s functional-image guidance covers both cases.
Charts and detailed diagrams
A short alt field cannot carry every figure in a complicated chart. Use it to identify the chart and its main point, then put the figures or explanation in nearby page text. Readers should be able to understand the information without relying on the picture. The W3C’s complex-image examples show several ways to handle richer information.
Images containing words
If important words appear only inside an image, make sure people who cannot see that image can still get the message. Sometimes that means including the words in the alt text; often it is better to put the message in ordinary page text, where it is easier to read and update. If the nearby text already conveys the full message, avoid announcing it twice.
How to add or change alt text in WordPress
- For an image already on a page: open the page or post in the block editor and select its Image block. In the block sidebar, use the alternative-text field to enter the description, or mark the image as decorative if that is the right choice. Update the page and check the result.
- For a newly uploaded or reusable image: open Media > Library, select the image and enter its Alt Text in the attachment details. WordPress can use this as the default when you insert that image elsewhere.
- For an image used in several places: review its important appearances separately. WordPress explains that alt text changed in an Image block applies to that particular page or post, while the Media Library value is a default for insertions. Do not assume one Media Library edit has corrected every image already published.
These steps follow the WordPress Image block documentation. If your site uses a page builder, gallery, theme template or background image, the controls may be elsewhere. Check the published page rather than assuming the Media Library field governs every instance.
What about image SEO?
Alt text can help Google understand an image alongside the surrounding page content. It is not a place to insert a list of target phrases. Google’s image SEO guidance recommends useful, contextual descriptions and warns against keyword stuffing. Write for the person who needs the alternative first; use a relevant search term only when it naturally describes what matters in the image.
For example, “Blue ceramic mug with white handle” may be useful on a product page. “Best blue ceramic mug UK cheap ceramic mugs buy now” is not. Nor should SEO pressure you into describing a decorative image that adds nothing to the page.
A quick check before you publish
- Read the page without looking at each image. Is any essential information missing?
- Check image-only links and buttons: is their action clear?
- Remove repeated descriptions of nearby text and leave genuinely decorative images empty.
- Make sure important chart data and words shown in images are also available as text.
- Check the published page, especially when images come from templates or a page builder.
Alt text is one part of making a site easier to use, not a complete accessibility fix. Our broader WordPress accessibility guide covers other areas to review. If your images or image links are built into a template that you cannot edit confidently, our WordPress website design page explains how we can help with the site itself.
Keep improving your website
Want practical WordPress advice in your inbox? Get our free site-care guide and join the newsletter. If you would rather discuss a problem on your website, Talk To Us.





