How to write alt text for images

  • alt-text
  • accessibility
  • seo
  • media-library
  • ai

Updated

Good alt text describes what an image shows in one short sentence, such as "Volunteer packing food boxes at the community pantry." Screen readers read it aloud, and search engines use it to understand the image. In WordPress, add it in the media library before you place the image on a page.

How do I add alt text in WordPress?

  1. Go to Media → Library and open an image, or select one in a media window from the editor.
  2. Find Alternative Text (sometimes shown as Alt Text).
  3. Describe what the image shows in a short sentence.

The media window saves as you type. On the full attachment edit screen, click Update.

Why didn't my alt text change on the page?

When you add an image with an Image block, WordPress copies the image's alt text into the block. Changing it in the media library later doesn't update blocks that are already on your pages.

To change the alt text of one image on one page:

  1. Select the Image block.
  2. In the block sidebar, edit Alternative text.
  3. Click Update.

What should alt text say?

Name the subject: "Volunteer packing food boxes at the community pantry." Don't use the file name, and don't start with "image of."

  • Photos: say who or what is shown and what's happening, if it matters. "Two nurses reviewing a chart at the front desk."
  • Products: include the name and the detail a shopper would care about. "Blue canvas tote bag with leather handles."
  • Logos: the organization's name, like "Acme Co. logo," or just "Acme Co." when the logo links to the home page.
  • Images with text: include the words in the image.

Write alt text for logos, heroes, and product photos. Leave it empty only for purely decorative images, like dividers or background textures.

If a photo appears in a cropping layout, set a focal point so the subject you described stays visible.

If your site runs on Dirigible

The alt text in the media library is the one that counts. When an image on a page has no alt text of its own, Dirigible shows the media library's alt text there automatically, so there's nothing to run after you add or change it. Alt text typed into a block always wins. Images marked as decorative stay silent; to keep any other image silent for screen readers, leave its alt text empty in the media library too.

To find images on your pages still missing alt text, run the Accessibility audit in Dirigible → Tools & Maintenance. It flags each one.

Draft alt text with AI

With Dirigible AI installed, Dirigible → AI Alt Text can write drafts for images that are missing a description. Read each draft before you rely on it.

See Generate alt text with AI to fill in every missing description at once, review the drafts, and have new uploads described automatically.

Plugin docs: Dirigible AI.