AltRelay – Alt Text Everywhere Wordpress Plugin - Rating, Reviews, Demo & Download
Plugin Description
The problem AltRelay solves
When you add an image to WordPress, you give it a description (called “alt text”) that helps screen readers and search engines understand what the image shows. WordPress stores this description in two separate places:
- The Media Library — the central place where all your uploaded images live.
- Each post or page — every time you insert an image, a copy of the alt text is saved inside that post’s content.
These two copies are independent. If you update the alt text in the Media Library, your posts keep the old version. If you fix it inside a post, the Media Library still has the original. And if an image had no alt text when you inserted it, every post keeps that empty copy, even after you describe the image later.
What AltRelay does
AltRelay connects these two places:
- Change alt text in the Media Library every post using that image is updated in the background.
- Change alt text on an image in the block editor when you save the post, the Media Library is updated, and from there every other post. The editor confirms it.
- A visitor views a page where an image has no alt text AltRelay fills it in from the Media Library on the fly, without saving anything. This covers posts, pages, synced patterns, templates, block widgets and text widgets.
There is nothing to configure. Activate the plugin and it works.
Decorative images
Some images only decorate and should be skipped by screen readers. Their alt text must stay empty. AltRelay never touches an image you mark as decorative:
- In the block editor on WordPress 7.1 or newer, tick WordPress’s own Mark as decorative checkbox in the Image block settings. On older versions, and for Cover and Media & Text blocks, AltRelay adds a Decorative image toggle to the block settings.
- Images hidden from screen readers in any other way (
role="none",role="presentation"oraria-hidden="true") are treated as decorative too. - To make AltRelay leave every image in a section alone, give the block around them, for example a Group, the CSS class
altrelay-decorative(Block settings Advanced Additional CSS class). AltRelay then fills and syncs none of their alt text, including in synced patterns inside the block. Images there that already have alt text keep it; empty them to make them silent. - On the Media AltRelay dashboard, the “Empty alt text in your content” list shows every image that has no alt text in a post but has one in the Media Library. Mark the decorative ones with one click, or fill the rest. The “Images marked decorative” list shows what is marked and lets you remove a mark again. Both lists can be narrowed to one content type.
- From the command line:
wp altrelay mark-decorativeandwp altrelay unmark-decorative.
An image that is the only content of a link cannot be marked decorative. Its alt text is what names the link, so without it a screen reader user hears a link with no name. AltRelay refuses and says why; remove the link first, or give the image alt text.
Why does marking matter? The block editor saves an empty alt for every image inserted without alt text, so an empty alt on its own almost always means “not written yet”, not “decorative”. AltRelay therefore fills unmarked empty alts. Leaving an informative image silent is the worse failure for a screen reader user, so the explicit mark is the safe default.
Review first
If your site already uses empty alt text on purpose, turn on Review first on the dashboard before anything is filled. While it is on, AltRelay leaves every existing empty alt alone: on your site, in the editor and when a description changes. Go through the review list, fill what should be described, mark what is decorative, then turn it off.
Who this plugin is for
- Site owners who reuse images across multiple posts and want consistent alt text.
- Content teams who want alt text changes to take effect sitewide without editing every post manually.
- Anyone who wants every informative image on the site to have a description.
Who should NOT use this plugin
- If you intentionally use different alt text for the same image depending on context (e.g. “Team photo” on one page, “Our staff at the retreat” on another) — AltRelay will overwrite those differences. It enforces one description per image, everywhere.
- If you need AI-generated alt text. AltRelay only syncs what you write — it does not create descriptions for you.
Important: read before activating
AltRelay changes the content of your posts when it syncs alt text. Please understand:
- Back up your database first. This is your safety net if you want to undo everything at once.
- Decide about decorative images first. After activating, open Media AltRelay. Review the “Empty alt text in your content” list, or turn on Review first if there is a lot to go through.
- One alt per image. If the same image has different alt text in different posts, AltRelay will replace them all with whatever you set next. The old per-post values are lost.
- Nothing is saved on activation alone. AltRelay only writes to posts when alt text changes.
- WordPress keeps revisions. Every post AltRelay updates goes through the normal WordPress save routine, so a new revision is created and you can restore any individual post from the post editor.
- Synced posts get a new “last modified” date, like after any other edit. A developer can switch that off with the
altrelay_update_post_modifiedfilter.
How changes happen — a quick guide
A visitor views a page
AltRelay fills in missing or empty alt text on the fly. Nothing is saved. Undo by deactivating the plugin.
You open a post in the editor
Empty alt text on images that are not marked decorative is filled from the Media Library, and the editor says how many images it filled. This does not count as a change: the post is not marked as edited, and nothing is written anywhere until you change something yourself and save. It works the same while the editor shows the template around the post.
You change alt text on an image block and save
The new value is sent to the Media Library, and from there to every post using that image. Discarding your edits sends nothing. Undo with post revisions or a backup.
An autosave sends nothing, because the text may still be half typed. When a draft was only autosaved, its alt text is sent the next time you save the draft yourself, if the Media Library still has no description for that image. Alt text inside a template part or synced pattern is sent when that part or pattern is saved.
You clear alt text on an image block
Only that post changes. The Media Library keeps its description, and the editor offers to mark the image decorative.
You change alt text in the Media Library
Every post containing that image is updated in the background. A post that someone has open in the editor meanwhile keeps the new text when they save it. Undo with post revisions or a backup.
You clear alt text in the Media Library
The empty value is synced to all posts containing that image. When you describe the image again later, every post gets the new text.
You deactivate or delete AltRelay
Changes already made stay in the database, and so do decorative marks. Undo with a backup only.
Supported blocks: core/image, core/cover (including fixed and repeated backgrounds), core/media-text, galleries, images inside synced patterns, and images in classic content.
Where AltRelay looks: posts, pages, custom post types, synced patterns, templates and template parts. Only posts that the person who made the change is allowed to edit are updated.
Syncing runs in the background. Changing alt text queues the work instead of doing it inside the request, and each run handles one batch of posts, so a site with thousands of posts never times out. Action Scheduler is used when it is available; otherwise WP-Cron. The dashboard shows updates that are still waiting, and any that failed. A post that cannot be saved does not stop the image’s other posts; once the cause is fixed, an editor or administrator can try those images again from the dashboard. If WP-Cron does not run on your site, they can also run the waiting updates from there.
Posts someone cannot edit are left alone. When an author changes an image’s description, posts by other people keep the old one. The dashboard says how many were skipped, and an editor or administrator can update them with one click.
What AltRelay does not cover
- Images it cannot tie to the Media Library. AltRelay recognises an image by the
wp-image-123class WordPress gives it, and only when the image file really belongs to that Media Library item. A block copied from another website keeps that site’s IDs; AltRelay leaves such images alone, and the editor tells you when it does. Replace the image from your own Media Library to connect it. - Content outside the post content. Page builders that keep their layout in custom fields, and image URLs stored in post meta or options, are not synced. Their output is not filled on the frontend either, unless the builder renders it through WordPress blocks. Developers can call
altrelay_fill_alt_text( $html )on such output. Excerpts are not synced either: a WooCommerce product’s short description keeps the alt text it was written with, while the product description is synced. - Markup that blocks from other plugins print themselves. Syncing works for any image in the post content. Filling on the frontend covers core blocks, including core Image blocks nested inside another plugin’s block; an image that such a block outputs on its own is not filled unless a developer adds the block’s name with the
altrelay_frontend_blocksfilter. - Block bindings and pattern overrides. When an image or its alt text comes from a binding, that source decides, and AltRelay leaves the block alone.
- Featured images, galleries made with the
shortcode, and site logos always read their alt text straight from the Media Library, so they need no syncing.
Command line: on sites with WP-CLI, wp altrelay audits and repairs from the terminal: a coverage summary, a full repair with a dry run, the review lists, filling and marking in one post or wherever an image is used, the state of the queue, and running it. wp help altrelay lists every command and option. Run commands with --user=<login> to apply that user’s editing permissions; a command that could not save a post exits with status 1.
For developers: filters, actions and functions let you change what is synced and how, or switch parts off. They are documented in the plugin’s README, together with every WP-CLI command.
Privacy: AltRelay makes no external requests, uses no cookies, and collects no data. It stores a plugin version, the Review first switch, a welcome-notice flag, a few short-lived cache entries, the list of waiting background updates when WP-Cron runs them, on images marked decorative wherever they are used a note saying so, or how far the marking has got, and on a post that was open in the editor during an update, the alt text the update replaced, for a day. All of it is removed on uninstall.
Screenshots
The AltRelay dashboard under Media: alt text coverage, the Review first switch, and inline editing for images that have no alt text yet.
Empty alt text in your content, with Fill and Mark decorative per image or in bulk. The images marked decorative have a tab of their own.
The Decorative image toggle in the block editor’s settings sidebar.

