How to add alt text in WordPress (and why it's not showing)

Add alt text in the block editor

This is the editor WordPress has used for posts and pages since version 5.0. These steps match WordPress 7.1.

1. Open the post or page and click the picture.
2. Look at the panel on the right. If it isn't there, click the Settings button next to Save or Publish at the top.
3. On the Content tab, type the description in Alternative text.
4. Click Save (or Update).

• Only this page: alt text typed here applies to the picture on this page or post, nowhere else.
• Galleries: a Gallery block is a set of pictures. Click each picture in it and fill in its own Alternative text.
• Pictures with words on top (a Cover block): its settings have an Alternative text box too.
• Pure decoration (a pattern, a divider): newer versions have a Mark as decorative switch, so screen readers skip the picture. Use it only when the picture tells people nothing.

Not sure what to write? How to write good alt text has examples, or the Alt text writer drafts it from your photo.

In the classic editor

If your posts look like a word processor with one big text box, you're in the classic editor. Click the picture, click the pencil icon, fill in Alternative Text in Image Details, then click Update, and update the post.

Add alt text in the Media Library

1. Go to Media, then Library, and click the picture.
2. In Attachment details, type the description in Alternative Text. It saves as soon as you click out of the box.

This becomes the alt text every time you add the picture to a page from now on. It doesn't change pages that already use it (see below). Most themes do use it for featured images, though, since those are drawn straight from the Media Library.

WordPress alt text not showing? Five reasons

1. You added it in the Media Library after the picture was on the page. The page kept its old, empty copy. Open the page, click the picture, fill in Alternative text there, and save.
2. You're looking for it on screen. Alt text isn't shown when you hover over a picture, and it isn't meant to be. It's read aloud by screen readers, and shown only if the picture fails to load. To see it, right-click the picture, choose Inspect, and look for alt="…", or run Picture Check on the page.
3. You saw an old copy of the page. If you didn't press Save or Update, nothing changed. If you did, a caching plugin or your web host may still be showing a saved copy: clear that cache, then hard refresh the page.
4. Your theme or page builder shows the picture its own way. Header pictures, sliders and backgrounds set in a theme's or builder's own settings often ignore the alt text in WordPress. Look for an alt text box in that element's own settings, or ask your web person.
5. It was marked as decorative. Then WordPress leaves the alt text empty on purpose. Switch Mark as decorative off and write the description.

Find every picture with no alt text

You don't need a paid alt text plugin: the box is built into WordPress. What's hard is finding the pictures that are missing it.

• PageKiwi for WordPress is our free plugin. Press Check my site and it lists Media Library pictures with no alt text, with a box beside each to type it in and save, and the posts and pages whose pictures have none, with a link to each.
• Picture Check looks at up to 10 pictures on a page of your live site, so it also catches pictures your theme or page builder added.

Saving alt text from PageKiwi's list sets the Media Library copy. Pages that already use the picture still need it filled in on the page, as in reason 1.

Is there a character limit?

WordPress doesn't limit the box. Keep it to about one sentence, around 125 characters, like this one. Longer details belong in the page's text.