Where to add image alt text in WordPress
Use alternative text to convey an image’s purpose in its context. A caption is visible explanatory text; a filename or media title is not a substitute for the image’s actual alt text.
Decide what the image communicates
Section titled “Decide what the image communicates”Look at the surrounding content. An informative image needs a concise description of the relevant information. A purely decorative image can have empty alt text so it does not add unnecessary repetition.
For a linked image, consider the link’s purpose as well. Avoid filling the field with keywords or beginning every description with “image of” when that adds no useful meaning.
Add or update the text
Section titled “Add or update the text”- Open the image’s Media Library details to review its Alternative Text field.
- Open the page where it is used. In an Image block, check the block’s alt-text setting and save the page after changing it.
- Add a caption separately if you want a visible explanation below the image.
- For a gallery or builder image element, use that element’s documented alt-text controls.
Changing the Media Library field later should not be assumed to update every existing use. A block or gallery can store its own copy of the image’s information. Check the page that visitors actually see rather than relying only on the library record.
Check the result
Section titled “Check the result”Inspect the rendered image’s alt value in the page or use an accessibility inspection tool. Confirm that the value is appropriate for this occurrence, and that the caption remains separate.
If the same image appears in different contexts, its best description may differ. The task is to make that particular use understandable, not to enforce one description throughout the whole site.
For selecting the image used by a blog card, see featured and content images.