Skip to content
Neartool
Checking…

Alt Text for WordPress: Add It to Images, Posts and the Media Library

WordPress stores alt text on each image in the Media Library, and lets you override it for a single use inside a post. This guide shows where to set it, how to handle a backlog of images, and what to write.

Where to Add Alt Text in WordPress

In the block editor

  1. Click an Image block.
  2. Open the block settings sidebar.
  3. Type your description in the Alternative text field.

For images that add no information, such as a purely decorative divider, use the option to mark the image as decorative (or leave alt empty) so screen readers skip it.

In the Media Library

  1. Go to Media → Library.
  2. Click an image to open its details.
  3. Fill in Alternative Text, and optionally Title, Caption and Description.
Alt text set in the Media Library is the default for new uses of the image. Images already inserted into old posts keep the alt text they had when they were inserted, so updating the library does not rewrite old posts.

Handling a Backlog of Images

Sites with hundreds of images without alt text are common. A practical way to catch up:

  1. Start with your highest-traffic pages and your product or hero images.
  2. Export the images you need, then run them through the alt text generator. It runs on your own device, so nothing is uploaded.
  3. Read and edit every draft. A model only sees the image, not your page.
  4. Choose WordPress JSON when you export. You get a file that maps each file name to alt text, a short caption and a description.
  5. Apply it with a script or WP-CLI. For example, to set the alt text of attachment 123: wp post meta update 123 _wp_attachment_image_alt "Blue ceramic coffee mug"
Back up your database before running any bulk update, and test on a few images first.

What to Write

  • Describe what the image shows and why it is on the page, in about 125 characters or fewer.
  • Skip "image of" and "photo of".
  • Never reuse the file name, and give each image its own text.
  • Don't stuff keywords. Write for people who can't see the image.

Paste your alt texts into the free alt text checker to catch length and quality problems before you publish. For more patterns, see 20 annotated alt text examples.