Alt text is the short written description attached to an image in a page’s HTML. Screen readers read it aloud, search engines index it, and browsers display it when an image fails to load. It is the only part of a photograph a blind visitor can actually use.
It is also the single most commonly skipped item on small-business websites. The 2026 WebAIM Million study, which scans the home pages of the top one million sites, found that 16.2 percent of images had no alt text at all, averaging 10.8 missing descriptions per page. Another 10.8 percent of images had alt text that was effectively useless — the word “image,” a file name, or a line copied from the caption right below it. One in four linked images had nothing.
None of that takes a developer to fix. It takes about twenty seconds per image and a clear idea of what you are writing and why.
Alt text is not the caption, the title, or the file name
WordPress gives every image in the media library four text fields, and they do four different jobs. Filling in the wrong one is a common and invisible mistake.
- Alternative text replaces the image for someone who cannot see it. This is the one that matters.
- Caption is visible to everyone, printed under the image. It adds context; it does not replace the image.
- Title is a leftover tooltip attribute. Most screen readers ignore it. Leave it alone.
- Description populates the standalone attachment page almost nobody visits.
In the block editor, alt text lives in the image block’s settings panel on the right, under Settings, labeled “Alternative text.” In the media library, switch to list view and you will see it on each attachment’s edit screen. Those are the only two places worth your time.
The question that writes the alt text for you
Stop trying to describe the picture. Ask instead: if this image vanished, what would the reader lose? Write that sentence. That is your alt text.
The same photograph gets different alt text on different pages, because its job changes. A photo of a timber-frame porch on a construction company’s project gallery might be “Covered timber-frame porch with exposed rafter tails and a flagstone floor” — the craftsmanship is the point. The identical photo in the site’s footer, behind the contact form, is decoration and needs no description at all.
Two habits to drop. Do not begin with “image of” or “photo of” — a screen reader already announces that it has reached a graphic, so you are making the listener hear it twice. And do not stuff keywords. Google’s own guidance treats alt text as content, which means keyword-loaded alt attributes read as spam to the search engine and as gibberish to the person listening.
Some images should have no alt text, and that is not a loophole
WCAG 1.1.1 — the baseline Level A requirement for text alternatives — asks for a description of images that convey information. Purely decorative images are supposed to be hidden from assistive technology instead, using an empty alt attribute: alt="". In WordPress, that means leaving the alternative text field blank.
Decorative means background textures, divider flourishes, abstract shapes, the stock photo of a laptop on a desk, and any image whose meaning is already stated in the text right beside it. Describing those does not help anyone. It forces a screen-reader user to sit through narration of your visual filler before reaching the sentence they came for.
The distinction matters more than it sounds, because automated scanners cannot make it. A tool can tell you an alt attribute is missing. Only a person can tell you whether it should be filled in or deliberately emptied.
How long should alt text be?
Aim for roughly 125 characters, or about 25 words. There is no hard limit in HTML, in Google’s index, or in any current screen reader — the 125-character figure survives from older software that chunked long strings, and JAWS still pauses around that point in line-by-line reading before continuing. It is a useful ceiling anyway, because concision forces you to decide what the image is actually for. Google counts roughly the first 16 words as a ranking signal, which lands in the same place.
If an image genuinely needs more than a sentence or two — a chart, a floor plan, an infographic — the answer is not longer alt text. Put the full explanation in the body copy or a caption where everyone can read it, and let the alt text point to it: “Bar chart of monthly donations, described in the paragraph below.”
Five images that trip up almost everyone
- Your logo in the header. It is a link to the home page, so describe the destination, not the artwork. The business name is enough — not “blue circular logo with mountain motif.”
- Any image of a linked button. If the image is the link, the alt text is the link text. Get it wrong and a screen reader announces a nameless link, which is why that one-in-four figure is the worst number in the WebAIM data.
- Images containing words. A graphic with “Fall Sale — 20% Off” set in type needs that exact text in the alt attribute. Better still, set it in real HTML so it is searchable and resizable.
- Product and portfolio photos. Describe the attribute a buyer is choosing between: “Walnut dining table with tapered legs, seats six,” not “table.jpg.”
- Staff headshots. The person’s name and role. Nothing about their expression or clothing.
Does alt text help SEO?
Yes, but modestly, and mostly for one job: it is the primary signal Google uses to understand what an image depicts, so it governs how your photos perform in image search. It is not a shortcut to ranking the page itself. Treat the SEO benefit as a side effect of describing images honestly, because the two goals happen to want the same thing — plain, specific, accurate language. Write for the listener and the search engine gets what it needs for free.
How to fix the images you already have
Do not start with the media library. A site with 900 attachments probably has 300 that are no longer used anywhere, and alt text on an orphaned file helps nobody. Start with the pages that get traffic.
- List your top ten pages by traffic, plus the home page and every service page.
- Open each one and work down the images in order, deciding decorative or informative before you write anything.
- Check the header logo and every image that functions as a link first. Those cause the most damage.
- Then let new images be handled at upload, so the backlog never rebuilds.
WordPress has no native way to bulk-edit alt text — the media library opens attachments one at a time — and plugins that generate descriptions automatically produce plausible sentences that miss the point of the image on that page. They are useful for triage on a large catalog of product shots. They are not a substitute for judgment on the pages that sell your work.
On the site for The ROCk, a new homelessness-response campus in Santa Fe, the image pass was one line item inside a WCAG 2.1 AA audit and remediation covering 17 page areas, an interactive property map, and an events calendar. Alt text was the fastest part of that work and the part a visitor using a screen reader notices first.
Where to start this week
Open your home page, turn off images in your browser, and read what is left. Every place you see an empty box with nothing beside it is a sentence you owe a visitor. Fix those, then the service pages, then stop — it is better to have twelve accurate descriptions than ninety generated ones.
Patrick Iverson is a brand strategist and custom WordPress developer in Santa Fe who has run an independent practice in New Mexico since 2001 and built on WordPress since 2003. If accessibility work keeps sliding down your list, or you want someone to go through a site and tell you honestly what needs attention, that conversation is worth having.
