Where do I add alternative text to WordPress images?

Definition: Alternative text is a text alternative for an image, stored in the HTML alt attribute. In WordPress, the Image block controls alternative text for an individual placement, while the Media Library supplies a default when an image is inserted.

Key facts

• As of 17 October 2026, WordPress's Image block documentation places Alternative text under the block sidebar's Content tab.
• The Media Library documentation lists Alt Text in the image's Attachment Details dialog and says changes there save automatically.
• WordPress's Edit Media documentation explains that an individually inserted image becomes disconnected from its library data.
• Google's image SEO guidance describes alt text as an input to image understanding alongside computer vision and page content.

Where are the editing fields?

WordPress's Media Library screen documentation describes opening an image's thumbnail in the library's grid view to display Attachment Details. The Alt Text field holds the image's text alternative. Edits in this dialog save automatically.

For an image already placed in a post or page, the Image block documentation locates Alternative text in the sidebar's Content tab. An edit in these block settings applies to that particular placement.

The distinction matters when reusing an image. The Edit Media documentation says library data supplies defaults at insertion time. Once an individual image is inserted, its data can be edited separately. A review of existing pages therefore includes their image blocks, even after the library record changes.

What do Title, Caption and Description do?

WordPress's Edit Media reference defines Title as the media item's name, Caption as a brief explanation and Description as an explanation of that media item. These are separate fields from alternative text.

The Image block reference describes a caption displayed below the image, with an Add caption toolbar control. It also provides a separate Title attribute field under Settings, then Advanced. That field supplies additional image text which many devices and browsers do not display. Checking the field label prevents a caption or media name from being mistaken for the image's alternative text.

What should appear in the HTML?

WordPress's Search Engine Optimization article identifies alt and title as attributes in image and link markup. For the image's text alternative, Google's image documentation gives this example:

<img src="puppy.jpg" alt="Dalmatian puppy playing fetch"/>

Here, src identifies the image file and alt supplies its text alternative. Google's guidance calls for useful descriptions that fit the page's context and warns against filling the attribute with keywords. A practical check after saving is to inspect the image element on the published page and read its alt value.

For a decorative image, W3C's Decorative Images tutorial shows an empty alternative:

<img src="topinfo_bg.png" alt="">

The tutorial defines decorative images as adding no information to the page and explains that an empty alternative lets assistive technologies ignore them.

Related terms

• Image alternative text
• Semantic HTML
• Googlebot-Image

FAQ

Will changing Media Library alt text update images already in posts?

WordPress's Edit Media documentation says individually inserted images become disconnected from library data. Review the image blocks in your existing posts separately.

Can I give the same image different alt text on different pages?

Yes. The Image block documentation says an alt-text edit in block settings applies only to that page or post.

Should I describe an image that is purely decorative?

W3C's decorative-image guidance uses an empty alt value for this purpose. In WordPress's Image block settings, you can mark the image as decorative.

Sources

1. WordPress, "Search Engine Optimization", updated 12 May 2026
2. WordPress, "Image block", updated 25 August 2026
3. WordPress, "Media Library screen", updated 6 June 2024
4. WordPress, "Edit Media", updated 23 October 2024
5. Google Search Central, "Google image SEO best practices", updated 2 March 2026
6. W3C WAI, "Decorative Images", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer