How to Add Alt Text in WordPress (WCAG 2.2)

Applies to: SC 1.1.1 Non-text Content, Level A · WordPress block editor (Gutenberg), block themes and the Media Library

Missing alt text was found on 53.1% of home pages in the WebAIM Million 2026 (detected with WebAIM's WAVE tool). 45% of images missing alt text were linked images, which leaves those links without a name (WebAIM).

This is the WordPress deep dive. For what good alt text says in the first place, start with the main guide, How to fix missing alt text, or the W3C alt decision tree.

First, the one thing that trips people up

WordPress stores alt text in two places:

• Media Library alt text is the image's default. WordPress uses it when you insert the image into a post or page after you set it.
• Block alt text (in the Image block's settings) applies only to that image on that one post or page.

So setting alt text in the Media Library does not fix images already placed in existing posts. The WordPress docs describe the split: block alt text "only applies to the image on that specific page or post", while Media Library alt text "sets the default alt text when you insert the image elsewhere" (Image block docs). After a Media Library clean-up, open the posts that use those images and check them.

Media Library

1. Go to Media › Library and click an image to open Attachment details.
2. Fill in Alt Text. WordPress describes it as the text "used for accessibility" (Media Library docs).
3. Title, Caption and Description are separate fields. The title is not read out as alt text, and a filename is not alt text.

You can also edit alt text from Media › Library › Edit more details (the Edit Media screen) (Edit Media docs).

Image block (block editor)

1. Select the Image block.
2. Open Block settings (the sidebar; click Settings next to Save/Publish if it's hidden).
3. Under Alternative text, describe the image's purpose, or choose Mark as decorative if it adds no information (Image block docs).

The block's crop/edit screen also has a Details tab with an Alt text field ("leave empty if the image is decorative").

Linked images: if the image links somewhere (a button-like banner, a "shop now" image), the alt text should describe the destination or action, e.g. alt="Shop the winter range", not how the image looks.

Featured images

Featured images are set in the post's settings sidebar (the Featured image panel), or from an Image block's More options › Set as featured image (Image block docs). There is no separate alt field for the featured image in the post sidebar. Depending on your theme and template, the featured image either uses the image's Media Library alt text or gets its text from somewhere else (see the Post Featured Image note below), so always check the front end.

• Set alt text on the image in the Media Library before (or after) choosing it as the featured image, then check the front end.
• In block themes, the Post Featured Image block can be set to Link to post, and archive and blog templates may have this turned on (Post Featured Image block docs). When it's linked, current WordPress versions can use the post title as the image's alt text instead of the Media Library alt text, so editing the Media Library alt may not change what's announced there. Check what the link announces on the front end, and whether the post title next to it is a second link with the same name.
• A Cover block that uses the post's featured image as its background can take its text alternative from that image's Media Library alt text rather than the Cover block's own Alternative text field. For a Cover block with its own image, set Alternative text in the Cover block settings (Cover block docs). If the image is only a backdrop for the heading, it can be decorative. Check the front end either way.

Galleries

Each image in a Gallery block is its own Image block (Gallery block docs). Select each image inside the gallery and set its alt text in the Image block settings. Galleries make alt text easy to miss, because images can be added in bulk.

• Images uploaded straight into a gallery are also added to the Media Library, so adding alt text there sets the default for future use, but check the gallery itself too.
• A dynamic gallery ("Use attached images") pulls in images attached to the post. Check that those images have Media Library alt text.
• A caption is not a replacement for alt text. If a caption already says everything the image shows, keep the alt short so screen reader users don't hear the same thing twice.

Decorative images

Use an empty alt (alt="") for images that add nothing: dividers, background textures, stock photos that only set a mood. In the Image block, use Mark as decorative, which WordPress says to use "only when it does not add meaningful information or functionality" (Image block docs). Be careful with blank fields: depending on your WordPress version and theme, an image whose alt field was simply left empty can be output with alt="", the same as a decorative image. A scanner then treats it as decorative and won't flag it. That makes a manual pass over informative images important even when a scan is clean. Check the page HTML if you're unsure.

Decorative means no information, not unimportant to you. A product photo, chart or photo of a named person isn't decorative.

Logos and other theme images

• Site Logo block: Link image to home is on by default (Site Logo block docs), so the logo is a link. Its alt text should name the destination, e.g. alt="Acme home". Set it in the Media Library or in the block's Details tab.
• Classic (non-block) themes: logos, header images and slider images are often set in Appearance › Customize or theme options. Whether they get alt text, and where it comes from, depends on the theme. Check the front end, and ask the theme developer if there's no field.

WooCommerce product images

WooCommerce product and gallery images are Media Library images, so set alt text on each one in the Media Library. WooCommerce's own docs note that a product video poster image needs alt text, and that without it WooCommerce falls back to the video's title (WooCommerce docs). Describe what distinguishes each product photo (colour, angle, detail), not just the product name repeated.

Page builders, sliders and other plugins

Page builders, slider plugins and gallery plugins often output images through their own widgets. Some read the Media Library alt text, some have their own alt field, and some output none at all. For each plugin you use:

• Check whether its image widget has an alt text field, and whether it falls back to the Media Library.
• Check images set as CSS backgrounds: they have no alt text at all, which is fine only if the image is decorative.
• AI alt text plugins can speed up a backlog, but review every suggestion before relying on it. A generated description can be plausible and still wrong, or describe appearance when the image is a link.

Menu names can change between platform versions (steps checked November 2026). If a path doesn't match, check your platform's current help pages. Page builder and plugin menus vary, so check each plugin's own docs.

WordPress and WooCommerce are trademarks of their respective owners. Glimscope is not affiliated with or endorsed by either of them.

What automated tools can and can't tell you: Automated checkers (including axe-core, which our monitor uses) can flag many instances of this issue, but they cannot judge everything. A human still has to check meaning and context. For scale: Deque reports that in its own sample of first-time audits, its automated tests found 57.38% of issues by volume (Deque report). That is Deque's figure for its sample, not a detection rate for any one tool, and it means a large share of issues still needs manual testing. A scanner can tell that an alt attribute is missing. It cannot tell whether existing alt text is accurate, or whether an image marked decorative really is. Automated tests find only some accessibility issues; manual testing is still required. Not legal advice. More on this: What automated accessibility testing can and can't catch.

Manual checklist

• Images already in published posts have alt text, not just the Media Library copies
• Gallery images each have their own alt text
• Featured images in blog and archive templates announce correctly on the front end (Media Library alt, post title, or another name — check what the link actually says)
• Linked images (logo, banners, product tiles) describe the destination
• Decorative images use Mark as decorative or an empty alt, and nothing informative is marked decorative
• No filenames, "image of…" padding or unreviewed AI suggestions
• Page builder, slider and WooCommerce images checked on the front end