How to Add Alt Text to Images in WordPress (Step-by-Step)
Alt text is what a screen reader speaks when it reaches an image, and what a search engine reads to understand it. In WordPress it is one field per image.
The field is easy to miss: WordPress never warns you when it is blank. Here is where to find it in all three editors, and what to write once you do.
Where WordPress keeps alt text
Every upload becomes an attachment, and WordPress stores the description in a meta field called _wp_attachment_image_alt. The key word is attachment: alt text belongs to the image file, not to the page you placed it on.
That explains most alt text confusion. Reuse a photo on a product page and in a blog post and it carries the same description to both. If the pages need different descriptions, write one that works in both places or upload a second copy.
Add alt text in the block editor
This is the route for new posts and pages on any current WordPress install.
- Open the post and select the image block. A blue outline appears around the image.
- Open the block sidebar with the gear icon in the top-right corner of the editor.
- Find the Alt text field and type your description.
- Click Update or Publish to save.
If the field is missing, check that you selected the image block itself.
Add alt text in the classic editor
Sites still running the classic editor, or page builders that open the classic media modal, use a different screen.
- Put the cursor where the image should sit and click Add Media.
- Select the image. The right-hand Attachment details panel opens.
- Fill in the Alt Text field, directly under the file name.
- Click Insert into page.
That panel also has Title, Caption, and Description fields. Only Alt Text becomes the alt attribute that assistive technology reads; the caption is visible on the page.
Add alt text from the Media Library
The Media Library is where you fix images that are already published.
- Go to Media → Library and switch to grid view.
- Click an image to open Attachment details.
- Type the description into Alt Text.
- To be sure it is stored, click Edit more details, check the field on the Edit Media screen, and click Update.
It is also the fastest way to audit an old site: open a dozen images and look at the field.
What good alt text actually sounds like
Good alt text describes the image's content and its purpose in that spot on the page. It is specific, it avoids wasted words, and it does not begin with "image of" — a screen reader already announces that it is an image.
| Image | Weak alt text | Better alt text |
|---|---|---|
| Team photo on an About page | team-photo-final.jpg | Five members of the support team standing outside the Bristol office. |
| Product shot of a linen shirt | shirt | Sand-colored linen shirt with a camp collar, photographed flat on white. |
| Screenshot of a dashboard | screen | AltMint review screen listing 12 images with missing alt text and a suggested description for each. |
| Chart of monthly revenue | chart | Bar chart showing revenue rising from January to June, with the steepest gain in April. |
| Divider between sections | decorative line | Empty alt attribute: alt="" |
Five to fifteen words covers most images. A chart may need a short paragraph, a decorative flourish nothing at all. Length is not the measure; usefulness is.
Rule of thumb: if the image disappeared and nothing in the surrounding text replaced its meaning, the alt text is doing its job.
Why context matters more than the picture
The same photograph can call for three different descriptions. A workshop photo could be "Participants sketching at a design workshop in Lisbon" on an events page, "Three people reviewing printed wireframes at a table" inside a tutorial, and "Attendees filling the main hall for the 2026 conference" in a news post.
Because alt text lives on the attachment, you cannot tailor it per page for free. Write the broadest accurate description, upload a context-specific copy, or set a per-block override if your builder supports one.
Context also changes when the image is a link. If a book cover links to a review, describe the destination — "Read our review of The Design of Everyday Things" — not the cover. Screen reader users navigate by link text.
The mistakes that make alt text pointless
- Filename dumps. "IMG_2041.jpg" describes a file, not a scene. If your alt text could have been generated by reading the file name, start over.
- Keyword stuffing. "cheap running shoes buy running shoes online running shoe sale" is unreadable aloud and looks like spam. Use the phrase once, and only if it fits the sentence.
- Empty alt on informative images.
alt=""tells assistive technology to skip the image. That is correct for decoration and wrong for charts, screenshots, and product photos. - Redundant phrasing. "Image of a photo showing a picture of a dog" wastes the listener's time. "A border collie waiting by a garden gate" does not.
- Forgetting generated images. Gallery blocks, sliders, testimonial avatars, and WooCommerce product galleries all render images that need alt text too.
A ten-minute audit
WordPress has no built-in report for missing alt text. The Media Library shows every image but not which ones are empty, so an audit means opening images one at a time. For fifty that is tedious; for five hundred it is a project.
Start with the images that matter: the homepage hero, the logo, product photos, and anything on your ten most visited pages. Fix those by hand while you are in the Media Library, then decide what to do about the archive nobody has opened since launch.
That archive is what an AI alt text generator is for. AltMint scans the media library and WooCommerce products, lists only the images with no alt text, drafts a description for each, and holds every suggestion until you approve it. Nothing is written to an image you already described. The free plugin is unlimited with your own AI key; Pro automation is on the pricing page.
Frequently asked questions
Does alt text still help SEO?
Yes, though not as a magic ranking switch. It gives search engines context about an image, which helps image search and supports the page. The more concrete benefit is accessibility: missing alt text is one of the most common WCAG failures.
Should decorative images have alt text?
They should have an empty alt attribute — alt="" — not a missing one. An empty value tells a screen reader to skip the image, which is right for dividers, flourishes, and spacer graphics. Leaving the attribute off entirely makes some screen readers read the file name instead.
How long should alt text be?
Long enough to replace the image, short enough to listen to. Most images need five to fifteen words; charts and screenshots may need two or three sentences. Past 125 characters, check whether every clause is earning its place.
Once the manual pass is done, the next problem is scale. If you are staring at hundreds of empty fields, read how to bulk edit alt text without breaking SEO before you install a plugin that promises to fill them all at once.