How to add alt text to images in WordPress

Short answer: open the image in the Media Library (or select the image block in the editor), find the Alternative text field, and type a short description of what the image shows. That description is read aloud by screen readers, displayed if the image fails to load, and used by Google Image Search to understand what the picture is.

The mechanics take ten seconds. Getting alt text right – useful for blind visitors, helpful for SEO, and not embarrassing when it surfaces in a search result – takes a little more thought. This guide covers both.

Why alt text matters#

Alt text (short for “alternative text”) is a plain-text description of an image, stored in the HTML alt attribute. It does three jobs:

• Accessibility. Screen readers announce alt text aloud so blind and low-vision visitors know what the image shows. Without it, they hear “image” or a filename like “IMG_4421.jpg” – useless.
• Fallback when images fail. Slow connections, broken URLs, blocked image domains – when the image does not load, the browser displays the alt text in its place. A site with good alt text is still readable; a site without it is full of empty boxes.
• SEO and image search. Google cannot “see” images. It reads the alt text, the surrounding content, and the filename to decide what the image is about. Alt text is one of the main ways a photo on your site ends up in Google Image results.

WCAG 2.1 AA, the accessibility standard most legal frameworks point at, requires meaningful alt text on informative images. This is not optional if your site needs to meet accessibility requirements.

Adding alt text in the block editor#

This is where most people add alt text day-to-day.

1. In a post or page, insert or click an existing Image block.
2. In the right-hand sidebar, open the Block tab.
3. Find the Alternative text field under Settings.
4. Type a short description of the image. One sentence is usually enough.

The alt text saves with the post when you update or publish. You can change it at any time without re-uploading the image.

If the sidebar is hidden, click the gear icon in the top right of the editor to show it.

Adding alt text in the Media Library#

If you want to set alt text once and have it reused every time you insert that image, do it in the Media Library instead:

1. Go to Media > Library in the WordPress admin.
2. Click the image (grid view) or click Edit (list view).
3. Fill in the Alternative Text field in the details panel.
4. Click away or close the modal – changes save automatically.

Alt text set in the Media Library becomes the default when you insert that image into a post. You can still override it per-insertion in the block editor if the context calls for a different description.

This is also where you set Title, Caption, and Description. They are all different fields for different purposes – only Alt Text is the accessibility and SEO field.

Adding alt text in the Classic Editor#

If your site still uses the Classic Editor (or a Classic block inside Gutenberg):

1. Click the image in the editor.
2. Click the pencil icon to Edit.
3. Fill in the Alternative Text field at the top of the image details panel.
4. Click Update.

Classic Editor uses the same underlying attachment metadata as the block editor, so alt text set here also updates the Media Library record.

What good alt text looks like#

Good alt text describes the image in the context of the page. Bad alt text either describes nothing, describes too much, or is clearly trying to manipulate search engines.

A few rules that work across almost every case:

• Describe what the image shows, not what it is. “A golden retriever running through tall grass at sunset” is better than “dog photo” or “image001.jpg.”
• Keep it short. Screen readers read the whole thing aloud without pausing. Aim for one sentence, usually 8-15 words. Long paragraphs are exhausting to listen to.
• Do not start with “Image of” or “Picture of.” Screen readers already announce that it is an image. Saying it again is redundant.
• Include the keyword naturally if – and only if – it fits. If the image is genuinely showing the thing the page is about, using the keyword is honest. If you are stuffing an unrelated keyword into every alt tag, Google notices and so does the visitor hearing nonsense read aloud.
• Match the context. The same photo of a keyboard might be “mechanical keyboard with RGB backlighting” on a review page, or “typing on a laptop at a cafe table” on a productivity article. Alt text describes what the image means here, not just what is in the frame.
• Do not repeat the caption. If you already have a visible caption underneath the image, the alt text should add information for non-sighted readers, not restate the caption verbatim.

Examples

Good:

• alt="WordPress block editor sidebar showing the Alternative text field" (screenshot illustrating a tutorial)
• alt="Barista pouring milk into a latte to form a rosetta pattern" (photo on a coffee blog)
• alt="Bar chart showing 45% faster page load times on NVMe storage compared to SATA" (infographic – summarize the data, not just “chart”)

Bad:

• alt="image" – tells nobody anything
• alt="IMG_4421.jpg" – this is the filename, not a description
• alt="best cheap wordpress hosting fast seo hosting 2026" – keyword stuffing
• alt="Picture of a picture of a dog" – redundant and weird

Decorative images: when alt text should be empty#

Not every image needs a description. If an image is purely decorative – a background pattern, a divider line, a generic stock photo that illustrates nothing specific – screen readers should skip it entirely. Making them announce it just slows down the person listening.

The way to tell a screen reader to skip an image is an empty alt attribute: alt="" . Not missing – empty. The distinction matters:

• alt="" – “This image is decorative, ignore it.” Screen readers skip it silently.
• No alt attribute at all – “I forgot to add alt text.” Screen readers may announce the filename or the URL instead, which is the worst outcome.

In the WordPress block editor, leaving the Alternative text field blank produces alt="" in the HTML. That is correct for decorative images. You do not need to type a space or a placeholder.

How to decide if an image is decorative:

• If removing the image would change what the visitor understands about the page, it is informative – write alt text.
• If the image is purely visual framing and removing it would not change the meaning, it is decorative – leave alt empty.

Hero images, header patterns, divider graphics, and most generic stock photos are usually decorative. Product photos, infographics, screenshots in tutorials, photos of people being quoted or featured, and diagrams are usually informative.

Bulk alt text management#

If you inherited a site with thousands of images and no alt text, adding it manually is a nightmare. A few approaches that scale:

• Filter the Media Library by missing alt text. The default library does not offer this filter, but plugins like Media Library Assistant or Alt Text Toolbox add it, so you can page through only the images that need attention.
• AI-assisted bulk alt text plugins. Several plugins (Alt Text AI, AI Alt Text Generator) use vision models to generate a first-pass description for each image. This is fine as a starting point, but you should review the output – AI descriptions can be inaccurate, too generic, or miss the context the image was chosen for.
• Export, edit, import. For very large libraries, exporting the attachment metadata via WP-CLI, editing the CSV, and importing it back is faster than any UI. This is for people comfortable on the command line – accidents are hard to undo.

Whichever route you take, do not paste the same alt text across hundreds of images. Duplicate alt text across a site is worse than no alt text – Google ignores it and screen reader users hear the same phrase repeatedly.

A quick alt text checklist#

Before publishing a post with images, a 30-second pass:

• Every informative image has alt text that describes what it shows.
• Every decorative image has empty alt text (blank field in the editor).
• No alt text starts with “Image of” or is a filename.
• No alt text repeats the caption word for word.
• No alt text is stuffed with unrelated keywords.
• Alt text is in the same language as the post.

That is the whole job. Alt text is one of the lowest-effort, highest-impact things you can do for accessibility and image SEO – and once it becomes a habit, you stop thinking about it.

If you are working through the broader set of site improvements, how to speed up WordPress covers image compression and lazy loading, which pair naturally with good alt text for a fast, accessible media library. How to add and embed videos in WordPress covers the equivalent accessibility considerations for video. And if you are cleaning up an older site in general, WordPress database optimization tackles the orphaned metadata that piles up when images are deleted without their attachment records.