Add the right alt text to WordPress images
Alternative text describes the useful meaning of an image when somebody cannot see it. In WordPress, an image block can have its own alt text, while the Media Library holds a default for future insertions. Updating the library entry is not a reliable way to update every image already placed across your website.
Before you start
- List the page and image you want to improve.
- Decide what that image communicates in this particular section.
- Check whether it is informative, decorative or the only content of a link.
What to do
Open the image in context
Edit the page and select the existing Image block. Read the nearby heading and caption. A photograph of a repaired roof might illustrate the repair method here but simply decorate a general contact page elsewhere; its purpose determines the useful description.
Write a concise alternative
Use the block’s alternative-text setting for the meaning that matters. Describe visible, relevant details without guessing materials, qualifications or results. Avoid repeating a caption word for word or filling the field with service names merely to target search terms.
Treat the media default separately
If the image will be reused, set a sensible default in the Media Library too. Then inspect its existing placements individually. A title used for organising your files and a caption visible on the page are not substitutes for correctly configured alt text.
Check the rendered result
Preview and save the approved change. Inspect the image’s alternative in the rendered page using an accessibility tool or browser inspection if you know how. A missing-image test alone can be misleading because some browsers display the filename or other fallback text.
What to check
- The description fits the actual image and page context.
- Previously inserted images have been checked individually.
- Decorative images do not add unnecessary repeated announcements.
Sources and further reading
Platform features can change. Check the provider’s current guidance before changing a live service.