Accessible images in WordPress are no dark art – the alt attribute has been built in from day one. And yet most websites fail exactly here. The reason is rarely bad intent, but WordPress’s specific architecture: alt text lives in several places at once, page builders do their own thing, and what’s maintained in the media library doesn’t automatically arrive everywhere.
This checklist is the WordPress counterpart to our platform-agnostic EAA checklist for e-commerce – here, it’s about the concrete steps and pitfalls inside the WordPress ecosystem.
1. The legal framework in brief
Three sets of rules matter for WordPress site owners – and all three converge on the same technical requirement for images:
| Framework | Applies to | Image requirement |
|---|---|---|
| EAA | E-commerce & certain services in the EU (since June 28, 2025) | WCAG 2.1 AA – text alternative (SC 1.1.1) |
| ADA | US market; ongoing lawsuit wave (4,500+ website suits in 2024) | De facto standard: WCAG 2.1 AA |
| WCAG 2.1 AA | The technical standard behind both | SC 1.1.1 (alt text) and SC 1.4.5 (images of text) |
The good news: meeting the WCAG requirements for images covers both EAA and ADA on this point simultaneously. There aren’t three different alt text standards.
2. Where WordPress stores alt text – and why it matters
The most common misunderstanding about WordPress images: the assumption that alt text is a property “of the image”. In reality, there are two storage locations:
Media library vs. post
Media library: the alt text on the media library entry is the template. It’s used when the image is newly inserted – and served directly for featured images.
Post/page: when inserting into the block editor, the alt text is copied into the block. From then on, both are independent: correcting the media library later does not change images already inserted into existing posts.
For your audit, this means: going through the media library isn’t enough. Existing content has to be checked where it’s actually served – in the rendered HTML. That’s exactly why a clean audit always works with the frontend (scan or source code), never just the backend.
3. The 8-point checklist
Scan the rendered website, not the media library: how many <img> elements have no or an empty alt attribute? The free accessibility scan delivers the per-page breakdown. Quick test for single pages: F12 → console → document.querySelectorAll('img:not([alt])').length.
Maintain alt text on the media library entry (“Alternative Text” field) – all future insertions and all featured images benefit. With hundreds of entries, this is where bulk generation comes in.
Because of the copy logic from section 2: already-published posts keep their old (or missing) alt text, even if the media library has long been corrected. Check top posts directly in the editor – the alt text field sits in the image block’s settings.
Dividers, ornaments, purely atmospheric images get alt="" – in the block editor, simply leave the field empty (the editor itself points this out). Important: the attribute must be present and empty. If it’s missing entirely, screen readers often read out the file name.
The most overlooked point: if an image is the only content of a link (logo → homepage, banner → sale page), the alt text describes the link destination, not the image: “Go to homepage” instead of “company logo”. An empty alt text makes the link unusable for screen reader users – so here, exceptionally, alt="" would be a serious error.
WCAG 2.1 AA (SC 1.4.5) requires real text instead of text graphics wherever possible (exceptions include logos). Promo banners with baked-in text are the classic case: if unavoidable, the alt text must carry the complete text information – “20% off all summer styles until Aug 31” and not “banner”.
Images in galleries, sliders, and builder widgets partly bypass the standard logic. Verify in the rendered HTML that the alt texts actually make it through – details on builder quirks in section 4.
Decide how every new image gets its alt text from now on – ideally automatically on upload to the media library, so the gap doesn’t reopen. Editorial rule to go with it: click through the image blocks once before publishing.
4. Gutenberg, page builders & themes: the quirks
In the block editor (Gutenberg), all is well: select the image block, maintain the alt text in the block settings, done. The editor even reminds you that empty alt text is reserved for decorative images.
It gets trickier outside the standard:
- Page builders (Elementor, Divi, WPBakery & co.) have their own image widgets with their own alt text fields. Some inherit the media library value, some don’t – never rely on it; check the rendered HTML.
- CSS background images (popular in builders for hero sections) technically can’t carry alt text at all. Rule of thumb: if the image carries information, it belongs in the content as an
<img>; if it’s pure decoration, a CSS background is actually the cleanest solution. - Theme images (logo in the Customizer, header images) have their own maintenance locations depending on the theme – the logo example from checklist item 5 is usually set in the Customizer or Site Editor.
5. Multilingual sites: WPML & Polylang
On multilingual WordPress sites, the topic multiplies – and is most often overlooked at the same time. A German alt text on the English page version doesn’t help English-speaking screen reader users and doesn’t rank in English image search. Accessibility and image SEO apply per language version.
- WPML: media translation manages separate translations of image metadata per language – including the alternative text. Check whether media translation is active at all: without it, every language version serves the same alt text.
- Polylang: same principle via its media translation feature – each language version of a media item carries its own alternative text that has to be maintained separately.
- Always verify in the frontend: open the same page in each language and check the rendered
altattribute – the translation plugins have too many configuration variants to trust the backend view.
Practically relevant: with AutoAlt.ai, multilingual costs nothing extra – 1 credit covers 1 image in any number of the 130+ supported languages. The effort for a trilingual site is the same as for a monolingual one.
6. The WooCommerce special case
If you run a WooCommerce store, all eight checklist items apply – plus one peculiarity: WooCommerce spreads product images across three maintenance locations (main image, product gallery, variation images inside the variations view). Variation images in particular slip through manual audits because they sit deep in the product editor. In addition, stores selling into the EU have been subject to the EAA since June 28, 2025 – the store-specific points (variants, category banners, traffic-based prioritization) are covered in depth in our EAA checklist for e-commerce; the technical implementation is shown on the WooCommerce integration page.
7. Test it yourself in 5 minutes
Before investing in tools or agencies: three quick checks show where your WordPress site stands.
- Console quick test: open any page, press F12, run
document.querySelectorAll('img:not([alt])').lengthin the console – this counts images with noaltattribute at all. Additionally,document.querySelectorAll('img[alt=""]').lengthcounts the empty attributes; reconcile that number with your actually decorative images. - Editor cross-check: open your most-visited post in the block editor and click through the image blocks – you’ll see directly whether the copy trap from section 2 has hit you (media library maintained, post outdated).
- Screen reader spot check: run VoiceOver (Mac, Cmd+F5) or NVDA (Windows, free) across a page. If file names are read out, attributes are missing; if there’s “noise” from described ornamental images,
alt=""is missing.
For the full overview instead of single pages: the free accessibility scan crawls the site and delivers the per-page breakdown.
8. Automation for existing and future images
Working through the checklist manually works up to a few dozen images. Beyond that, a tool should sensibly take over the legwork: the AutoAlt.ai plugin for WordPress generates AI alt text for the entire media library in bulk, covers new uploads automatically, and writes to the real alt attribute – with protection for alt text you’ve already written manually. For how the AI generation works technically and where its limits are, see how AI alt text generators work.
What can be automated – and what can't
Describing, phrasing, translating: automation. The editorial decisions in the checklist – decorative vs. informative (item 4), link destination descriptions (item 5), text-in-image cases (item 6) – remain human spot-check work. This combination brings a typical WordPress site to compliance level in hours, not weeks.
9. FAQ
Why does my image have different alt text in the post than in the media library?
WordPress copies the media library alt text into the post when the image is inserted. After that, the two are independent: changes in the media library don’t retroactively affect already-inserted images. Existing content therefore has to be checked in the post itself.
How do I mark an image as decorative in the block editor?
Simply leave the alt text field empty – the block editor itself notes that empty alt text is meant for decorative images. WordPress then renders alt=””, which screen readers correctly skip.
What about linked images, e.g. a logo linking to the homepage?
If an image is the only content of a link, the alt text must describe the link destination, not the image: “Go to homepage” instead of “company logo”. An empty alt text would be a serious error here, because the link becomes unusable for screen reader users.
Are images containing text allowed?
WCAG 2.1 AA (SC 1.4.5) requires real text instead of images of text wherever the same presentation is possible with real text. Exceptions include logos. Where text in an image is unavoidable, the alt text must convey the complete text content.
Is an accessibility plugin enough to make WordPress images compliant?
Overlay widgets that inject alt text via JavaScript write nothing into the source code – no SEO value, and the approach is controversial in the accessibility community. Only alt text that lives in the HTML alt attribute is both compliant and SEO-effective.
Checklist item #1: done in 2 minutes.
The free accessibility scan checks your WordPress site and shows per page where alt text is missing.