Skip to content
Knowledge Base

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.

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.

  1. Open the image’s Media Library details to review its Alternative Text field.
  2. 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.
  3. Add a caption separately if you want a visible explanation below the image.
  4. 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.

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.