WP Image Alt Manager

A safer way to clean up missing image alt text in WordPress.

WP Image Alt Manager turns useful image filenames into editable alt-text suggestions. It gives site owners, content teams, and agencies a review-first workflow for improving Media Library accessibility without blindly overwriting existing work.

Everything runs inside WordPress. There is no external AI service, no public endpoint, and no image data is sent to a third party.

What the plugin helps you do

• See how many Media Library images have missing alt text.
• Preview filename-based suggestions before making changes.
• Search, filter, review, and edit suggestions in one dashboard.
• Apply selected changes or process all high-confidence suggestions in safe batches.
• Pause and resume a large cleanup without skipping images.
• Undo the most recent plugin run while preserving later manual edits.
• Optionally fill blank alt text for future high-confidence uploads.
• Inspect and edit images directly from a page using the admin-bar scanner.

A review-first workflow

The plugin uses the real uploaded filename—not the attachment title—to prepare a suggestion.

For example:

family-enjoying-the-beach-1200x800-scaled.jpg

becomes:

Family Enjoying the Beach

WordPress-generated dimensions, duplicate suffixes, scaled, rotated, edit hashes, separators, and file extensions are cleaned up automatically.

Suggestions are then classified as:

• Safe suggestion: the filename appears descriptive enough to review and apply.
• Needs review: the filename looks generated, generic, numeric-heavy, unusually long, or otherwise unreliable.

Camera filenames, screenshots, UUIDs, stock identifiers, and similar low-confidence names are never selected for automatic bulk updates.

Getting started

1. Download the repository ZIP from GitHub using Code → Download ZIP.
2. In WordPress, open Plugins → Add New Plugin → Upload Plugin.
3. Upload the ZIP and activate WP Image Alt Manager.
4. Open Media → Alt Text Manager.

The compiled runtime assets are included in the repository, so a downloaded copy can be installed without running a build first.

Using the Alt Text Manager

Review and apply selected images

1. Open Media → Alt Text Manager.
2. Search or filter the review queue.
3. Check each thumbnail, filename, and suggestion.
4. Edit the suggested text when needed.
5. Select the rows you want to update.
6. Choose Apply selected.

Existing non-empty alt text is never overwritten by the bulk workflow.

Apply all safe suggestions

Choose Apply all safe suggestions to process high-confidence filenames in stable batches of 50 attachment IDs. Before every write, the plugin confirms that the image still has blank alt text.

If a run is interrupted, return to the manager and resume it. Images marked Needs review remain unchanged.

Undo the latest run

Choose Undo last run to restore alt text changed by the most recent plugin operation. If someone edited an updated value afterward, that newer edit is preserved.

Fill blank alt text on future uploads

The Optional filename auto-fill setting can fill blank alt text for new uploads with high-confidence filenames. It is disabled by default, and low-confidence uploads remain blank for review.

Scan a page from the front end

While logged in as an administrator:

1. Open a page on the front end.
2. Choose Scan image alt text from the WordPress admin bar.
3. Click a highlighted Media Library image.
4. Review or edit its alt text and save.

This is useful when the correct description depends on how an image is being used on a specific page.

Important accessibility guidance

Filename suggestions are a starting point—not a replacement for editorial judgment.

Good alt text describes the image's purpose in its page context. Decorative images should generally use an empty alt attribute. Avoid keyword stuffing and do not add details that are not visible or relevant.

Safety and privacy

• Administrator-only interface and actions
• Capability checks and WordPress nonces
• POST-only update, scan, settings, and undo requests
• Server-side validation and escaped output
• No public REST route, shortcode, or standalone update endpoint
• No external API calls or image uploads
• No custom database table
• Only the latest bulk-run record and a small settings option are stored

Requirements

• WordPress 5.0 or later
• PHP 7.2 or later
• An administrator account

The current release has also been verified with WordPress 7.0.1 and PHP 8.1.29.

Development

Install dependencies and run the available checks:

npm install
npm test
npm run build

Create the installable plugin archive:

npm run build:zip

The archive is written to dist/ with one top-level wp-image-alt-manager/ directory and excludes Git metadata, source maps, node_modules, and development source files.

Release highlights

2.0.0

• Added the Media Library review dashboard.
• Added filename confidence classification and editable suggestions.
• Added stable cursor batching, resume support, and protected undo.
• Added optional high-confidence auto-fill for new uploads.
• Secured all changes behind administrator permissions, nonces, and POST requests.
• Simplified and repaired the current-page scanner.
• Added repeatable tests and installable ZIP packaging.

Support and feedback

Please use GitHub Issues to report a bug or suggest an improvement.

License

WP Image Alt Manager is licensed under the GNU General Public License v2.0 or later.