How to Add Image Alt Text in WordPress (Correctly)

Updated 7 November 2026 · Standard formula, shown below

Adding alt text to images in WordPress improves accessibility for screen reader users and helps search engines understand your images. This guide shows you how to add alt text in the WordPress block editor and classic editor, and explains how to write alt text that is both descriptive and effective.

What You’ll Need

Access to your WordPress admin dashboard (wp-admin).
Permission to edit posts or pages (usually Editor or Administrator role).
The image you want to add alt text to, either already uploaded to your Media Library or ready to upload.

Step-by-Step

Log in to WordPress. Go to yoursite.com/wp-admin and enter your credentials.
Open the post or page editor. Go to Posts or Pages and click Edit on the content where you want to add or change alt text.
Select the image block. In the block editor (Gutenberg), click on the image you want to edit. A toolbar and a sidebar will appear.
Locate the Alt Text field. In the right sidebar, under the Image settings tab (the block settings icon that looks like a square with two columns), find the Alt text field. If the sidebar is not visible, click the gear icon in the top-right corner.
Enter your alt text. Type a concise, descriptive phrase that explains what the image shows. For example, “Golden retriever puppy sitting on green grass.”
Save or update. Click Update in the top-right corner to publish your changes.
For the classic editor: If you are using the classic editor, click on the image and then click the pencil icon (Edit). In the Image Details dialog, find the Alt Text field, enter your text, and click Update.
Adding alt text to existing Media Library images: Go to Media → Library. Click on any image, and in the attachment details panel on the right, find the Alt Text field. Type your description and click Update.

Common Mistakes

Leaving alt text blank. Empty alt text is fine for purely decorative images (use alt=""), but for informative images, it’s a missed opportunity for accessibility and SEO.
Using “image of” or “picture of”. Screen readers already announce that it’s an image, so this is redundant. Start directly with the subject.
Keyword stuffing. Cramming multiple keywords or phrases like “best running shoes, buy running shoes, cheap running shoes” is bad for users and search engines. Keep it natural.
Writing overly long alt text. Alt text should be short and to the point—usually under 125 characters. If you need more detail, use the image caption or surrounding text.
Repeating the page text. If the image is accompanied by a caption that already says the same thing, the alt text can be shorter or even empty.

Tips

Describe the function, not just the appearance. If the image is a button or link, describe where it goes, e.g., “Link to the contact page” instead of “Blue button”.
Be specific. “A person holding a smartphone” is better than “A person with a device”. Include relevant details like color, action, or context if they matter.
Use punctuation. Alt text is read as a sentence, so use periods or commas to make it readable.
Check for existing alt text. Some themes automatically use the image title or caption as alt text, which may not be appropriate. Always review.
Use the same alt text for the same image across your site. Consistency helps avoid confusion.

Troubleshooting

Alt text field not showing. Make sure you have selected the image block, not the group or column block. If you still don’t see it, try clicking the image itself and look for the “Alt text” field in the block toolbar (a pencil icon).
Changes not saving. Always click Update or Publish after editing. If you’re using a page builder (like Elementor), the alt text field may be in the image widget settings, not the default block editor.
Alt text appears in code but not on the front end. Some themes or plugins strip alt text for lazy-loaded images. Check if a lazy-load plugin is interfering, or inspect the page source to confirm the alt attribute is present.
Alt text is not visible to visitors. Alt text is only shown if the image fails to load; it’s not a tooltip. That’s normal.
Can’t edit an image that’s inside a gallery. Click the gallery block, then edit each individual image within it. In the block editor, select the image inside the gallery and the alt text field will appear in the sidebar.

Frequently Asked Questions

Is alt text required for every image?

No. Purely decorative images (like a background pattern) should have empty alt text (alt="") so screen readers skip them. Informative images should have descriptive alt text.

Does alt text help SEO?

Yes, but only slightly. Search engines use alt text to understand image content, which can help your image appear in Google Image search. It’s not a major ranking factor for regular web pages, but it’s still good practice.

What is the difference between alt text and a caption?

Alt text is invisible to most visitors and is used by screen readers and search engines. A caption is visible text displayed below the image, often used to provide context or credit.

Can I use the same alt text for all images?

No. Each image should have unique alt text that describes that specific image. Using the same text for all images is unhelpful and can be seen as spammy by search engines.

How long should alt text be?

Aim for under 125 characters. This is roughly the limit that screen readers will read aloud before pausing. If you need more detail, put it in the surrounding text.

Does the image title or file name matter?

The file name and image title are separate from alt text. While they can help SEO, they are not used by screen readers. Always fill in the alt text field explicitly.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.