Skip to main content

WordPress Alt Text: How to Write and Add It

  • November 11, 2026
  • 8 min read
  • By CYPHEX
WordPress Alt Text: How to Write and Add It

WordPress alt text is the short written description attached to an image, so that people and software that cannot see the picture still get its meaning. This guide is for site owners and editors. It covers how to write good alt text, where to add it in WordPress, what Google actually says about it, and how to deal with a media library full of undescribed images.

What is alt text for an image?

Alt text is the value of the alt attribute on an image tag. It is a short text alternative that is read aloud by screen readers, shown when the image fails to load, and used by search engines to understand what the image shows.

In HTML it looks like this: <img src="oak-desk.jpg" alt="Oak standing desk with a laptop and a lamp">. In WordPress you rarely touch the HTML. You type the text into an “Alternative Text” field and WordPress writes the attribute for you.

How to write an image description

Describe what the image shows and why it is on the page, in one short sentence, as if you were reading the page to someone over the phone. Leave out “image of” or “picture of”, because screen readers already announce that it is an image.

A few rules that cover most cases:

  • Say what matters in context. The same photo of a laptop needs different text on a product page than on an article about remote work.
  • Keep it short. One clear sentence is usually enough. Long descriptions belong in the page text or a caption.
  • Skip keyword lists. Google’s guidance on images tells site owners to write useful, relevant text and not to fill alt attributes with keywords.
  • Describe a linked image by where it goes. If the image is a link, the alt text acts as the link text, so say what the link does.

Six good and bad examples

SituationBadBetter
Product photoshoesRed leather running shoes, side view
Blog hero imageimage1.jpgDeveloper reviewing a checklist on a laptop at a desk
Keyword stuffingcheap wordpress theme best wordpress theme buy themeScreenshot of a portfolio theme with a three-column layout
ChartchartBar chart showing support tickets falling each month from January to June
Logo as a linklogoCYPHEX home page
Team photoPicture of our teamFour team members standing outside the office entrance

The bad versions are vague, a filename, or written for a search engine. The better ones pass a simple test: if the image vanished, would the reader still get the point?

Decorative images: when to leave alt text empty

If an image is purely decorative, give it an empty alt attribute (alt="") so screen readers skip it. Do not leave the attribute out entirely, because then some screen readers read the filename instead.

W3C’s guidance on success criterion 1.1.1 says purely decorative content, meaning content that only serves an aesthetic purpose with no information or function, does not need a text alternative, but should be implemented so assistive technology can ignore it. Typical examples are divider swirls, spacer images and background textures. Adding descriptions to those only distracts people using screen readers.

If the image adds information the text does not already give, describe it. Otherwise leave it empty.

How to add alt text in WordPress

There are three common places. Media Library. Go to Media, then Library, and click an image. In the details panel, fill in “Alternative Text” and save. This sets the default alt text for that file wherever it is inserted later.

Block editor. Click an Image block. In the block settings sidebar, find the “Alternative text” field and type the description. Changes made here apply to that block on that post. Newer versions of WordPress also show a “Mark as decorative” option next to it, which sets the alt attribute to empty. If you do not see it, leave the field empty for decorative images.

Classic editor. Click the image in the editor, then the pencil (edit) icon. Fill in “Alternative Text” in the image details window and update. When inserting from the Add Media window, the same field appears in the attachment details on the right.

Alt text typed into a block belongs to that block, while Media Library text is the default for the file. If an image shows the wrong description, check both.

Does alt text help SEO?

Yes, in the limited way Google describes. Alt text helps Google understand what an image is about. Google’s image guidance on Search Central says Google uses alt text along with computer vision and the content of the page to understand the image, and that alt text is useful as anchor text when an image is used as a link.

That is the extent of the claim. Google does not say that adding alt text lifts your pages in rankings, and we are not going to say it either. What the guidance does say is that stuffing alt attributes with keywords gives a poor experience and may be treated as spam. Write for the reader, and any search benefit follows from the image being understood.

For the wider picture on file size, formats and loading, see our WordPress image SEO guide and the technical image SEO guide.

Alt text and accessibility

Accessibility is the stronger reason to do this properly. WCAG success criterion 1.1.1, Non-text Content, is a Level A requirement: non-text content needs a text alternative that serves the same purpose. A blind visitor using a screen reader depends on your alt text for every image that carries information. Missing or vague text means they get a gap, or a filename read out loud.

Why is alt text showing instead of the image?

The browser shows alt text when it cannot display the image, which means the file did not load or is not available. Alt text is doing its fallback job.

Common causes on WordPress sites:

  1. The file is missing or the URL is wrong. Often after a migration, a domain change, or deleting files from the uploads folder.
  2. Mixed content. An http:// image on an https:// page can be blocked.
  3. A plugin or CDN problem. An optimisation, lazy loading or CDN setting can break image URLs.

Open the image address in a new tab. A 404 error means the file is gone.

Fixing alt text across a big media library

Doing this one image at a time is fine for a small site. On a library with thousands of images, it needs a system:

  1. Find the gaps first. List which images have no alt text, so you know the size of the job.
  2. Start with what visitors see most. Fix images on key landing pages, product pages and recent posts before the archive.
  3. Use a draft-then-review process. A tool or a person drafts text, and an editor checks it before it goes live.
  4. Mark decorative images as decorative instead of inventing descriptions.

Where Image Hunter’s AI alt text fits

Image Hunter is a free WordPress plugin made by CYPHEX, available on WordPress.org. It is released under the GPL and has no paid tier. Alt text is one part of it, alongside stock photo search, WebP conversion and media auditing.

Here is what its product page and WordPress.org listing say, and nothing more:

  • AI-written metadata. The plugin can write titles, alt text and captions. The product page says you add your own API key for the AI provider, with Groq given as the example for titles, alt text and captions. The key is stored in your WordPress.
  • You review the text. The product page says you review the text before it is saved and can edit every word.
  • Auditing existing images. A media audit flags missing alt text, duplicates, broken images and weak file names, with previews and a way back for fixes.
  • Bulk tools. The WordPress.org listing describes a Bulk Toolkit and a confirmation step before a bulk tool runs on multiple selected images.

Two points we could not confirm from those pages: which model analyses the image itself, and whether alt text generation works without a provider key. The WordPress.org listing also lists the outside services the plugin can contact, including Groq, so read that list before installing on a site with privacy requirements.

AI alt text is a draft, not a finished answer. It can misread an image, miss the reason the image is on the page, or describe a decorative image that should be empty. Always read what it produced, especially for charts and images with text. Our AI alt text guide covers a review routine in detail.

Frequently asked questions

What is alt text for an image?

Alt text is a short written description in an image’s alt attribute. It is read by screen readers, displayed when the image cannot load, and used by search engines to understand the image.

How do I write a good image description?

Describe what the image shows and why it matters on that page, in one short sentence, without “image of” and without stuffing keywords. If the image is purely decorative, leave the alt text empty instead.

Does alt text help SEO?

It helps Google understand what an image is about, and Google’s image guidance says it uses alt text alongside computer vision and the page content. Google does not say alt text boosts rankings, and keyword-stuffed alt text can look like spam.

Why is alt text showing instead of my image?

The browser could not load the image file, so it is showing the fallback text. Check for a missing file, a wrong URL after a migration, mixed http and https content, or a plugin or CDN setting that rewrites image addresses.

If your site has a large backlog and you want help setting up a review process, get in touch.

Stock photography provided by Pexels under the Pexels License.

Need a feature your site does not have?

We build small, clean plugins and connect your tools so you do not repeat work by hand.

Comments

  1. Loading comments...

Leave a comment

Free quote

Get a clear plan and fixed price

Tell us what you need in three quick steps. No obligation, no jargon, and no pressure.

Step 1 of 3

Tell us what you need

Three quick steps. We reply within one business day.

What do you need help with? Pick all that apply