WordPress accessibility: themes, plugins and alt text
WordPress accessibility depends on three layers: your theme, your plugins and the content you publish. The accessibility-ready theme tag is a manual review result, not a WCAG AA claim. Set alt text in the Media Library or the Image block, then test the published pages, because plugins can change what visitors receive.
Published . Last reviewed .
This page is general information, not legal advice. For the laws that may apply to your site, start with our accessibility laws overview or the tool that shows which laws apply to you. Every WordPress fact below comes from WordPress's own documentation, was read on October 11, 2026, and links to its source. GotAlt is not affiliated with WordPress.
Who controls what on a WordPress site
A WordPress page is assembled from layers, and a visitor's browser receives only the combined result. A problem can enter at any layer, so a label on one layer does not tell you how the page behaves.
| Layer | What it usually decides | Where to check it |
|---|---|---|
| Theme | Templates, navigation, focus styles, colors, layout at different zoom levels | The theme's review status (below), then your own published pages |
| Plugins | Forms, sliders, popups, galleries, shop and booking widgets, anything that adds markup | The published page, because plugin output is not covered by a theme label |
| Content | Alt text, headings, link text, document language, PDFs and embeds | The editor fields you fill in, then our heading checker and link text checker |
What the WordPress project says about itself
The WordPress project's accessibility page states an aim of making the WordPress Admin and the bundled themes meet WCAG 2.2 at level AA, where possible. It also says the project cannot guarantee that every theme meets that bar, and that themes labeled accessibility-ready were checked by the Theme Review Team against the project's basic accessibility requirements (WordPress accessibility statement, last modified September 19, 2024). Two limits are worth noting. The target is about the Admin and the themes that ship with WordPress, not about the pages you publish. And the same page's authoring-tool section names WCAG 2.0 at level AA, so even the project's own page cites two versions; our which-version guide explains why that matters.
What the accessibility-ready theme tag means
The WordPress Theme Review handbook says a theme can be approved to use the accessibility-ready tag after it passes a manual accessibility review against the minimum requirements in the Accessibility Team's theme guidelines. A new theme carrying the tag may not go live in the theme directory until it has passed that audit, and adding the tag to a live theme without approval can lead to suspension from the directory (Theme Review handbook, accessibility section).
The same handbook page is explicit about the limit: the tag "does not mean that the theme meets the WCAG guidelines AA-level." The May 2026 announcement explains why. WCAG does not apply directly to themes, because it measures content and a theme is the wrapper around your content (WordPress Accessibility Team, May 6, 2026). Treat the tag as a useful starting point for choosing a theme, and as no statement about your site's pages.
What changed in May 2026
The announcement, published May 6, 2026, says the theme guidelines now contain requirements only: the earlier recommendations were removed, and each guideline follows a standard format of principle, testing and WCAG resources. Five requirements were added, and theme authors were given until June 30, 2026 to begin updating their themes, either to update their accessibility or to remove the tag. The announcement does not say what happens to themes that missed that date, so check a tagged theme's last update date and its accessibility.txt file. The guidelines now list 18 items (Guidelines for the WordPress accessibility-ready tag), and the Theme Review handbook keeps its own list of the same 18 headings (required items, last modified May 12, 2026).
| Requirement | What the requirement page describes, and what to check |
|---|---|
| Support for reflow, resize and text spacing changes | The requirement page describes testing at 200% and 400% zoom in a 1280 pixel wide window without sideways scrolling, and checking that text stays readable when line, letter, word and paragraph spacing are increased. Do the same on your main pages. See WCAG 2.2 explained for the related criteria. |
| No unexpected changes of context | The requirement page says a theme must not load a new page, submit a form or open a new window unless the user was warned or started it. Tab through your forms and menus and watch whether anything fires on focus or on change. |
| Content on hover or focus is accessible | The requirement page asks for hover or focus content to be dismissible without moving the pointer or focus, reachable by keyboard and kept visible while hovered. Try the Escape key on your menus and tooltips. |
| Accessibility statement | The theme must ship an accessibility.txt file in its top-level folder describing its audit status, testing method, accessibility features and how to report issues (requirement page). That file is about the theme. It is not a statement for your website, which our accessibility statement guide covers. |
| Must not recommend or require inaccessible plugins | A tagged theme may not suggest, bundle or require a plugin with known accessibility barriers, and any plugin it does recommend must also meet the standard (requirement page). Testers install the recommended plugins and run the tests again, so a plugin problem counts against the theme. |
The other 13 guidelines include a skip link, landmark roles, keyboard navigation, labeled form fields, heading structure, sufficient color contrast and alternative text on images and graphics. If a theme carries the tag, check when it was last updated and whether its author has addressed the May 2026 changes.
How to add alt text in WordPress
WordPress gives you alt text in more than one place, and the place decides how far the text travels. The Image block documentation describes the difference: alt text typed in the block settings applies only to the image on that page or post, while alt text saved in the Media Library sets the default when you insert the image elsewhere (Image block, updated August 25, 2026).
| Where | How to reach it | What it affects |
|---|---|---|
| Media Library | In Grid View, click an image to open the Attachment Details dialog and fill in the Alt Text field. The documentation says changes there save automatically (Media Library screen). | The default text each time you insert that image later |
| Image block settings | Select the Image block, open the block settings and use Alternative text on the Content tab. | That image on that page or post only |
| Mark as decorative | On the same Content tab, tick Mark as decorative for an image that adds no information, so assistive technology can skip it. | That image on that page or post only |
| Media editor, Details tab | Select Crop in the block toolbar, then Details. The Alt text field there is for describing the image, or leaving empty if it is decorative. | The image's metadata, edited without leaving the editor |
These steps follow WordPress documentation updated in August 2026. The Image block changelog records the Mark as decorative section and the new media editor as August 2026 changes, and refers to screenshots for WordPress 7.0. If you do not see Mark as decorative or the Details tab, your WordPress version likely predates them; the Alternative text field and the Media Library Alt Text field are the longer-standing routes.
The block settings link to the W3C's alt decision tree, which helps you choose between a description and an empty value. Our complete alt text guide and alt text examples cover the same decisions with before and after wording, and alt text for product images applies them to shops.
Two consequences follow from how the fields work. First, the Image block documentation describes the Media Library field as the default for new insertions. In practice that means posts that already use the image may keep the text they were given, so after you improve the default, check those posts on your own site. Second, a filename or a leftover caption in the field is easy to miss because the field looks filled. This is the case a presence check cannot catch. Our alt text checker opens the image file and compares it with the description on the published page.
The result you want in the page source is an alt attribute that matches the image, or an empty one for decoration:
<img src="team-lunch.jpg" alt="Five colleagues around a table sharing a meal">
<img src="divider.png" alt="">Plugins: categories, not recommendations
Plugins matter because they add markup that neither your theme nor your editor fields control. We do not name a plugin as making a site accessible, and neither should a plugin listing. Start with the plugins you install specifically for accessibility, because they differ in what they actually do to the page:
| Type | What it can do | What to confirm |
|---|---|---|
| Checkers and scanners in the dashboard | Report issues found in your content or rendered pages, so you can fix them at the source. | Does it only report, or does it change the published HTML? Does it test the rendered page or only the editor content? Which checks are rule-based, and what does it say it cannot test? |
| Alt text helpers and AI alt text generators | Suggest or bulk-fill alt text across the Media Library or existing posts. | Does it write to the Media Library default or to each placement? Who reviews each description before it goes live? Does it send your images to an outside service? |
| Markup patch plugins | Add skip links, landmarks, labels or focus styles through code. | Does it duplicate what your theme already outputs? Does the page still pass a keyboard test after it runs? |
| Overlay and toolbar widgets | Add a front-end toolbar or script that adjusts the page for each visitor. | Does it fix the source of a problem or layer a script over it? Read the overlay warning below before installing. |
Plugins that are not about accessibility also change what visitors receive. These are the categories worth testing on the published page:
- Forms. Check that every field has a visible label, that errors are announced in text, and that the form works from the keyboard. Our free scan flags fields with no label.
- Sliders, galleries and carousels. Check controls for names, alt text on each slide, and a way to pause movement.
- Popups, banners and chat widgets. These are usually added by script after the page loads, so an automated scan of the HTML cannot see them. Open them yourself with the keyboard.
- Shops and booking tools. Product images and checkout steps come from the plugin. Test the whole path as a visitor.
- Page builders. They can produce deep or skipped heading levels and empty wrapper links. Run the heading checker on pages built with them.
- Performance and image optimization tools. They rewrite markup. Compare alt text before and after you switch one on.
Be careful with overlay plugins
Some plugins add a toolbar or widget that promises to fix accessibility automatically. In April 2025 the FTC issued a final order requiring accessiBe to pay $1,000,000; the complaint charged that claims its product would make a website WCAG-conformant, and would keep ensuring conformance automatically, were false or unsubstantiated (FTC press release). Fix the source of a problem instead of layering a widget over it. Our overlay comparison explains the difference.
What GotAlt checks on a WordPress site, and what it cannot see
GotAlt reads the HTML your WordPress site sends to an ordinary, signed-out visitor. Nothing is installed in WordPress, and no admin access is needed. The free scan runs rule-based checks, each mapped to a WCAG criterion and listed on our methodology page, including images with no alt attribute, filename-style alt text, missing form labels, empty links and buttons, page language and the page title. The deep audit additionally opens up to six images per page and judges whether the alt text is true of each one.
What a scan of your published pages cannot see
- The block editor and any admin screen, including drafts, private posts and password-protected pages.
- Content that a plugin or script adds after the page loads, such as popups, cookie banners, chat widgets and client-rendered sliders.
- Computed color contrast, keyboard traps, focus order and what a screen reader announces, because these need a rendered page and real interaction.
- Anything behind a login, including member areas and shop accounts.
Automation covers only part of WCAG. Karl Groves wrote that an automated tool can definitively test approximately 25 to 29 percent of best practices for WCAG 2.0 (source), which is why the routine below includes manual checks. For color pairs, use the contrast checker; for text on photos, the image contrast checker; and for a hands-on pass over a live page, the accessibility bookmarklet.
What to recheck when something changes
WordPress sites change in small steps, and each kind of change puts a different layer at risk. Use the table as a trigger list rather than a calendar.
| When this changes | Recheck this |
|---|---|
| You switch or update a theme | The theme's tag, its accessibility.txt and last update date, then keyboard use, zoom and your main templates. |
| You install or update a plugin | Every page where the plugin appears, by keyboard only: menus, popups, forms and sliders. Updates rewrite markup, so rescan afterward with the free scan. Our testing guide shows the full method. |
| You upload or replace images | The Media Library alt text first, then the placements that need different wording. Mark decorative images as decorative. |
| You edit page layouts | Headings and links with the heading checker and link text checker, plus the most common accessibility errors list. |
| Time passes | On paid plans, a weekly deep audit reruns on the pages you nominate and catches regressions. Otherwise, rerun the free scan on a few pages each month. |
For the standard behind all of this, see the WCAG 2.2 checklist, WCAG 1.1.1 Non-text Content and WCAG 1.4.3 Contrast (Minimum). Related platform guides: Shopify, Wix, Squarespace and Webflow. A broader plan is in how to make a website accessible.
Sources and verification dates
Each source below was read on October 11, 2026. We re-read them when we update this page, and our editorial policy explains how corrections are handled.
- WordPress accessibility statement, WordPress.org, last modified September 19, 2024.
- Accessibility-ready requirements updated, WordPress Accessibility Team, published May 6, 2026.
- Theme Review handbook, accessibility.
- Theme Review handbook, required accessibility items, last modified May 12, 2026.
- Guidelines for the WordPress accessibility-ready tag, including the reflow, context change, hover and focus, accessibility statement and plugin requirement pages.
- Image block documentation, last updated August 25, 2026.
- Media Library screen documentation, last updated June 6, 2024.
- FTC press release on the accessiBe final order.
WordPress accessibility questions
Is WordPress accessible out of the box?
It depends on the theme, the plugins and the content you publish. The WordPress project states a WCAG 2.2 AA aim for its Admin and bundled themes where possible, and says it cannot guarantee all themes. That aim is not a statement about your published pages. The editor gives you alt text fields and a decorative option, so scan your pages and test them by keyboard.
Does an accessibility-ready theme make my site meet WCAG AA?
No. The Theme Review handbook says the tag does not mean the theme meets WCAG at AA level, and the Accessibility Team notes that WCAG measures content while a theme only wraps it. Your content and plugins still need checking.
Which accessibility plugin should I install?
We do not recommend a plugin as making a site accessible. Compare plugins by what they do to the published HTML: checkers report, alt text helpers write text that someone must review, and overlay widgets add a script. Prefer fixing problems at the source in your theme, editor and Media Library. The FTC's 2025 order against accessiBe concerned the kind of automatic-fix claim some widgets make.
I changed the alt text in the Media Library. Why do old posts still show the old text?
The Image block documentation describes Media Library alt text as the default used when you insert an image, while text set in a block applies to that placement. In practice, posts that already use the image may keep their own text, so open them and check each placement.
Does GotAlt need a plugin or admin access?
No. GotAlt works against any live URL by reading the HTML a signed-out visitor receives, so there is nothing to install. It cannot read drafts, password-protected pages or content behind a login.
Will fixing these issues protect me from a lawsuit?
No tool can promise that, and this is not legal advice. Fixing real barriers helps real visitors. See our ADA website guide and, for EU shops, the EAA guide.
See what your WordPress pages send to visitors
Run a published page through the free scan to find missing alt text, unlabeled fields and empty links, then read the report against what the scan cannot see.
Scan my site for free See a real report first