How to add alt text in WordPress

WordPress gives you several places to add alt text, and they don’t all behave the same way. The most common confusion, which comes up again and again on r/Wordpress (for example “Bulk copying alt text from media library to existing posts”, May 2026), is that changing alt text in the Media Library doesn’t change images you’ve already inserted into posts. This guide covers each method and explains that behaviour so you fix the right thing.

Method 1: in the block editor (per image, per post)

1. Open the post or page and select the Image block.
2. In the block settings sidebar, find Alternative text.
3. Type a description, or mark the image as decorative if it adds no information.
4. Update or publish the post.

WordPress’s documentation describes this field as letting you “add meaningful alternative text to an image or mark it as decorative”, and links a “Describe the purpose of the image” decision tree (WordPress.org: Image block). The decorative toggle outputs an empty alt (alt=""), which is correct for purely decorative images (our guide).

Important: the same documentation says, “If you add alt text in the block settings, that edit only applies to the image on that specific page or post. Adding alternative text for an image in the Media Library sets the default alt text when you insert the image elsewhere” (same source).

The Media & Text block has its own alt text field in its settings (WordPress.org: Media & Text block). Cover blocks and gallery blocks have their own controls too, so check each block type you use.

Method 2: in the Media Library (the default for future use)

1. Go to Media › Library.
2. Click an image to open Attachment details (or the Edit Media screen).
3. Fill in Alternative Text.

The Edit Media screen is where you manage “meta data such as title, caption, alt text, and description” (WordPress.org: Edit Media).

What this does: - Sets the default alt used when you insert this image into a post from now on. - Is typically what your theme uses when it outputs images through WordPress’s attachment functions at render time, which often includes featured images and many theme or plugin galleries. Whether a given template reads the library alt depends on how the theme is coded, so check the rendered page.

What it does not do: - It does not rewrite the alt inside posts where the image is already inserted. When you insert an Image block, the alt is saved into that post’s HTML. That’s why “I fixed it in the library but the checker still says it’s missing” is so common.

Method 3: the classic editor

If you use the Classic Editor plugin or a Classic block:

1. Click Add Media, then select or upload the image.
2. In Attachment Details, fill in Alternative Text before clicking Insert into post.
3. For an image already in a post, click it, click the pencil (edit) icon, and change Alternative Text in the Image Details dialog.

Same rule as above: the alt is written into the post content when the image is inserted.

Featured images

Featured images are output by the theme, not stored inside your post content, so they usually reflect the Media Library alt when the page loads. Set the alt on the image in the Media Library. If your theme hard-codes something else (for example the post title, or nothing), that’s a theme issue: check the rendered HTML and ask your developer or theme vendor.

A featured image at the top of a post is often decorative if the post title already says what it shows. In that case an empty alt is fine.

WooCommerce product images

WooCommerce product images and galleries are Media Library attachments, so set alt text in the Media Library or from the product’s image selector. See our guide to product image alt text for what to write, especially for gallery images (each one should say what it shows).

Page builders (Elementor, Divi and others)

Page builders often have their own image widgets with their own alt settings, which may override, ignore or default to the Media Library alt. Check the builder’s image widget settings and, above all, check the rendered page. That’s the only place that tells you what a screen reader will actually get.

Fixing alt text in bulk

If you have hundreds of existing posts with missing alt:

1. Find the gaps on the rendered pages, not just in the library. A site crawl or the Altpass site audit lists each page, each image and its current alt.
2. Fix the library first (it sets defaults and fixes theme-rendered images like featured images).
3. Then fix in-content images. Options: - Edit posts manually, starting with your highest-traffic pages. - Use a plugin that updates alt text in post content, not just in the library. Test it on a staging copy first, and back up your database. - If you’re comfortable with WP-CLI, you can update library alt text programmatically. Attachment alt text is stored in the _wp_attachment_image_alt post meta field (for example wp post meta update 123 _wp_attachment_image_alt "Sage-green ceramic mug, side view"). This updates the library default, not existing post HTML.
4. Stopgap if you can’t edit quickly: the Altpass fix script can apply approved alt text in the browser while you work through the source. It’s a temporary patch. The fix belongs in WordPress, and the CSV export is there to help you do it.

What to write

Quick reminders (full method in how to write good alt text):

• Describe the purpose in context. The same image can need different alt text in different posts, which is exactly why WordPress lets you set it per block.
• Linked images need alt text that describes the destination (guide).
• Don’t paste the file name. WordPress doesn’t fill alt text automatically, but some upload plugins and imports do, and “DSC_4892” helps nobody.
• Mark decorative images as decorative rather than leaving the field blank by accident.
• Don’t stuff SEO keywords. Google warns that keyword-stuffed alt “may cause your site to be seen as spam” (Google Search Central).

FAQ

My SEO plugin says “image has an empty alt attribute”. Is that wrong? Only if the image is decorative. Empty alt is correct for decoration and wrong for informative images. Look at each flagged image and decide.

Should alt text and the image title be the same? No. The title attribute is rarely announced consistently and shows as a hover tooltip. Put the description in alt, and don’t rely on title for anything important.

Does WordPress add alt text automatically? Not in core. Several third-party plugins generate it with AI. Whatever you use, review the output. AI drafts often describe what’s in the picture rather than why it’s on the page.

Check your WordPress site

Run the free Altpass checker on a few posts. Because it reads the rendered page, it shows what visitors actually get, including images where the library has alt text but the post doesn’t.

Updated 2026-10-07