How to Write Alt Text for WordPress Images
Good alt text answers one question: what would someone miss if this image did not load? Write that, in a sentence, in the image's Alternative text field, and leave the field empty when the image is pure decoration. That is the whole method. It is also why the usual shortcuts do not work: a template that pastes your post title or focus keyword into every image produces a filled-in field, not a description, and a filename echoed back is worse than nothing because a screen reader now reads out something that sounds deliberate. The field being populated is not the goal. The picture being described to someone who cannot see it is the goal.
The short version
- Ask what the image is doing on the page. Informative, decorative, functional or an image of text. The answer decides everything that follows.
- Write what a person would miss, in one sentence, in plain language. No "image of", no keyword list, no product name you have already written in the heading above it.
- Leave decorative images empty. An empty alt attribute is a real answer, and often the correct one.
- Read back anything a tool wrote for you before it goes out, because the failures are silent.
What alt text is actually for
The requirement people are usually trying to meet is WCAG success criterion 1.1.1, and its wording is more useful than most summaries of it. It asks that "all non-text content that is presented to the user has a text alternative that serves the equivalent purpose". Not a description of what is in the picture. An alternative that does the same job.
That distinction settles most arguments. A photograph of a jumper on a product page and the same photograph in a blog post about wool are doing different jobs, so they need different alt text. A decorative swirl at the top of a section is doing no job that words could carry, so it needs none. The criterion says so explicitly: if non-text content "is pure decoration, is used only for visual formatting, or is not presented to users, then it is implemented in a way that it can be ignored by assistive technology". And when the image is a control, the rule changes again: "if non-text content is a control or accepts user input, then it has a name that describes its purpose".
Two questions get you there faster than any checklist:
- Why is this image here? What is it adding that the surrounding text does not already say?
- What would someone miss if it did not load? Write that. If the answer is "nothing", you have found a decorative image.
Four kinds of image, four different answers
The W3C's own alt decision tree sorts images by what they do. In practice, four cases cover almost everything on a WordPress site.
| Kind of image | What the alt text should be | Example |
|---|---|---|
| Informative: carries meaning the text does not | A brief description conveying that meaning | Dalmatian puppy playing fetch |
| Decorative: adds atmosphere only | W3C's instruction is plain: "use an empty alt attribute". In WordPress that means leaving the Alternative text field blank | A background texture, a divider, a stock photo of a laptop next to a paragraph that already explains itself |
| Functional: it is a link or a button | The destination or the action, not the picture. W3C: use the alt attribute "to communicate the function of the image" | A magnifying glass that runs a search is Search, not magnifying glass icon |
| Image of text: the words exist only in the picture | The words themselves | A logo lockup, a quotation set as a graphic, a price badge |
The case people get wrong most often is the decorative one, because an empty field looks like an oversight and a filled one looks like diligence. It is the other way round. Alt text on a decorative image adds noise to a screen reader's pass through the page, which is a real cost paid by a real person to make a field look tidy.
Why templated alt text fails
The common shortcut is a rule: paste the post title, or the product title, or the SEO focus keyword, or a tidied-up version of the filename, into every image that has no alt text. It scales beautifully. It also produces, on a page with eight images, eight identical strings that describe none of them.
WebAIM's annual survey of a million home pages, published in February 2026, is the best evidence of how widespread this is. It found that "16.2% of all home page images (10.8 per page on average) had missing alternative text", and separately that "10.8% of images with alternative text had questionable or repetitive alternative text, such as alt='image', 'graphic', 'blank', a file name, etc." Its own summary of the two figures together: "more than one in four images on popular home pages have missing, questionable, or repetitive alternative text."
Read that second figure again, because it is the one this page is about. Those images passed the check that most plugins and audits perform, which is whether the attribute is present and non-empty. They still failed the person using them.
The SEO argument for templating is weaker than it looks too. Google's own image guidance asks you to "focus on creating useful, information-rich content that uses keywords appropriately and is in context", and then says the quiet part directly: "avoid filling alt attributes with keywords (also known as keyword stuffing) as it results in a negative user experience and may cause your site to be seen as spam". A rule that stamps your focus keyphrase onto forty images is the practice that sentence describes.
None of which makes rule-based tools worthless. They are genuinely useful for coverage on a site that has none, they are instant, and the good ones are reversible. The mistake is finishing there and recording the site as done.
Writing it in WordPress: where the field is, and what it is not
Alt text lives on the image, not on the post. In the Media library, open an image and the Alternative text field is the first one in the details panel. In the block editor, select an Image block and the same field appears in the block settings sidebar. Both write to the same place, which has a consequence worth knowing: the alt text is stored against the attachment, so it travels with the image everywhere that image is used.
That is convenient and it is also the method's one real limitation. If the same photograph appears in a blog post as an illustration and on a product page as the product, its correct alt text differs between the two, and WordPress gives you one field. Where it matters, the fix is to set the alt on the specific block rather than relying on the attachment default, or to upload the image twice for two genuinely different jobs.
The three fields next to it do different work and none of them substitutes:
- Title is an internal label. Browsers may show it as a tooltip on hover, which is no use to a keyboard or screen reader user, and it is not a text alternative.
- Caption is visible to everyone, printed under the image. Useful, but it is read in addition to alt text, not instead of it. If the caption already says everything, that is a case for a shorter alt or an empty one, and worth thinking about rather than duplicating.
- Description populates the attachment page, which most sites never show anyone.
Filenames are worth two minutes as well. Google asks for filenames that are "short, but descriptive", and contrasts my-new-black-kitten.jpg with IMG00023.JPG. That will not save a missing alt attribute, but it is the difference between a helpful fallback and a meaningless one when something goes wrong further down the line.
WooCommerce product images
Product images are where the templating habit does the most damage, because the pattern "product title as alt text on every image" is exactly what a shop's bulk tools offer, and it is exactly wrong. The product name is already on the page, in the heading, and it is read out before anyone reaches the gallery. Repeating it five times tells a shopper nothing about the five pictures.
What a buyer using a screen reader actually needs from a product gallery is what each shot shows that the others do not:
- The main image: the product itself, described the way you would describe it to someone over the phone. "Navy wool jumper, crew neck, ribbed cuffs", not "Navy Wool Jumper - Buy Online - Free Delivery".
- Gallery shots: the angle or detail each one adds. "Close-up of the ribbed cuff and knit texture". "Back view showing the shoulder seam". "Worn by a model, mid-thigh length on a tall frame".
- Scale, fit and finish shots: the information the picture exists to convey. "Mug beside a standard 330ml can for scale" carries the fact the photograph was taken for.
- Variation images: name what changes. If the colour is the variation, the colour belongs in the alt text, because that is the difference the image is there to show.
- Badges and icons: a "Free delivery" graphic is an image of text, so the alt text is the words. A decorative flourish beside the price is decoration, so leave it empty.
There is a commercial argument here as well as an ethical one, and it does not need overstating. Descriptions of what is in your photographs give search engines and shopping surfaces genuine text about the product, which a repeated title does not. That is a modest gain, made honestly, and it is the kind Google's guidance actually asks for.
What the tools do, and where each one breaks
There are three approaches on the market, plus whatever your SEO plugin already does, plus doing it yourself, and the differences matter more than the feature lists suggest. Figures checked on WordPress.org on 26 September 2026.
| Approach | What it reads | Where it breaks | What it costs you |
|---|---|---|---|
| Rule engines, for example Bialty (10,000+ active installs, 4.2 stars) and Auto Image Attributes From Filename, with its paid Image Attributes Pro add-on (100,000+ active installs, 4.8 stars) | Text you already have: SEO focus keyword, post or product title, cleaned filename. Bialty's own documentation is refreshingly plain that "it does not visually analyze images". Auto Image Attributes works from the filename; the Pro add-on adds the post title, your SEO plugin's focus keyword and custom tags | Every image on a page gets the same or nearly the same string, which is the "questionable or repetitive" category above. It cannot tell a decorative image from an informative one | Nothing per image and no external calls. Bialty injects at render time and "does not rewrite Media Library metadata", so nothing in your database changes. Auto Image Attributes does write to the Media Library, and Pro lets you choose to "preserve existing attributes and add missing attributes only" or to overwrite them, so choose before a bulk run |
| Hosted vision AI, for example Alt Text AI (20,000+ active installs, 4.7 stars) | The image itself. Sends "your image and your site's URL" to its API. Adds product names for shops, focus keyphrases from your SEO plugin, 130+ languages and WP-CLI | It describes what is in the frame, which is not always what the image is for, and it will happily describe a decorative divider. Keyphrase injection can reintroduce the stuffing problem | An account and credits, and an external service in your publishing path |
| Hosted vision AI inside a wider service, for example ShortPixel Image Optimizer (300,000+ active installs, 4.5 stars), and Rank Math's Content AI | The image itself. ShortPixel can also pass "the parent post or page title along with the image", so it sees a little of the page. Rank Math's listing says its bulk alt text sends "image data (base64-encoded)" to its Content AI service | The same frame-not-purpose blind spot as any vision tool. ShortPixel's page context helps with relevance but is still a title, not the reason the image is there | An account with the vendor. ShortPixel needs its own API key, with "100 AI credits per month" free and paid plans above that, and keeps your existing alt text unless you tell it otherwise. Content AI needs a connected Rank Math account and draws on Content AI credits. Worth a look if you already pay for either service |
| Vision AI without a key: AltoGraph, ours (fewer than 10 active installs, no ratings yet) | The image itself. Sends the image URL, the filename and a hashed site ID, and nothing else | Same blind spot as any vision tool: it reads the picture, not the page, so it cannot know an image is decorative and will write alt text where an empty field is the right answer | Free for 10 items a month, no API key and no account. Newest and least proven of the tools here, with the smallest install base on this table |
| What your SEO plugin already does: Rank Math (4,000,000+ active installs) and Yoast SEO (10,000,000+) | Rank Math's free "Add missing ALT attributes" setting fills empty alt text from a template, %filename% by default, and applies it "dynamically", so the Media Library is unchanged and only images in post or page content are covered. Yoast SEO does not write alt text; its free check looks at whether your alt text reflects your focus keyphrase | Rank Math's default is a rule engine by another name, and a filename is exactly what WebAIM counts as questionable. Yoast's check is sensible as written, since it nudges you the other way on "every single image stuffed with the same keyphrase", but it measures keyphrase coverage, not whether the text describes the picture | Nothing extra, since you probably have one installed already. Yoast says AI-drafted alt text is "coming soon" to its Bulk Editor, not yet shipped as of this check |
| By hand | The page, the purpose and your own judgement | It does not scale, so in practice a backlog never gets done and the field stays empty | Roughly thirty seconds an image, and it is the only approach that gets the decorative case right by default |
The sensible combination for a site with a real backlog is not one of these, it is two: a generator to clear the images that have nothing, then your own pass over the pages that matter, fixing the decorative ones and rewriting the shots where purpose beats appearance. That is a smaller job than it sounds, because the pages that matter are a short list.
The failure the tools will not tell you about
Every automated approach has a path where it cannot do the job and writes something anyway. A rule engine with no title to work from falls back to the filename. A vision tool that cannot reach the image, because the media is behind a login, on a staging domain, or in a format the service does not read, falls back to whatever it has, which is usually also the filename. The result is dsc-4021-final-v2 read aloud in a voice that gives no hint it is a guess.
This is the same category WebAIM counts as questionable alt text, and it names file names in the list explicitly. It is worth being direct that this is not a hypothetical for us: our own plugin had a version where the service's filename fallback was presented in the admin as though the AI had written it, and the fix was to label it plainly and tell the owner to rewrite it, rather than to hide it. A tool that cannot say which of its outputs it is confident about is asking you to trust all of them equally.
So the question to ask of any alt text tool, before a catalogue goes through it: what does it do when it cannot do the job, and does it tell me? If the answer is that it writes something and reports success either way, the review step is not optional.
AltoGraph adds an Alt text column to your media library, so the images with none are visible at a glance, with a Generate button on each one and a bulk action for a backlog. It reads the image itself rather than your keywords, it leaves alt text you have written alone, and when it cannot read an image it says so instead of passing a filename off as a description. Automation is off until you switch it on. Free on WordPress.org: 10 items a month, no API key and no account.
Get AltoGraph on WordPress.orgA review checklist
Whether the text came from a person or a tool, six checks catch nearly everything. They take about ten seconds per image.
- Purpose, not contents. Does it say what the image is doing here, rather than listing what is in the frame?
- Would it stand in? Read the page with the images replaced by their alt text. Does it still make sense?
- Decorative images empty. Anything that adds atmosphere only should have nothing in the field.
- No duplicates. Two images on a page with identical alt text means at least one of them is wrong.
- No padding. Drop "image of", "photo of", "graphic showing". Screen readers already announce that it is an image.
- No keyword stuffing, and no filenames. If the text reads like a search query or a file reference, rewrite it.
On a large site, do this properly on the pages that earn the traffic and the money, and sample the rest. Complete coverage of poor alt text is worth less than good alt text on the pages people actually reach.
Frequently asked questions
Does alt text help SEO?
A little, and less than the shortcuts assume. Google uses alt text to understand what an image shows, and asks you to "focus on creating useful, information-rich content that uses keywords appropriately and is in context". The same guidance warns against the tactic most often sold as an SEO win: "avoid filling alt attributes with keywords (also known as keyword stuffing) as it results in a negative user experience and may cause your site to be seen as spam". Descriptive alt text earns the modest benefit. Stuffed alt text risks the opposite, and fails the people it exists for either way.
What alt text should a decorative image have?
None. The W3C's decision tree says to "use an empty alt attribute", which in WordPress means leaving the Alternative text field blank, and WCAG 1.1.1 makes the same point: an image that "is pure decoration, is used only for visual formatting, or is not presented to users" should be "implemented in a way that it can be ignored by assistive technology". Writing something anyway does not make the page more accessible. It adds one more thing to listen to before reaching the content.
Is AI-generated alt text good enough for accessibility?
It is better than an empty field on an informative image, and it is not a finished job. A vision model describes what is in the frame, and alt text is meant to serve the image's purpose on that page, which the model cannot see. It also has no way of knowing that an image is decorative and should be silent. Used as a first pass over a backlog, followed by your own read of the pages that matter, it is a genuine time saver. Treated as a switch that makes a site accessible, it produces filled fields and the same underlying problem.
Do WooCommerce product images need alt text if the product name is on the page?
Yes, and the product name is the wrong thing to put in it. The heading has already been read out by the time anyone reaches the gallery, so repeating it adds nothing. Describe what each shot shows that the others do not: the angle, the detail, the scale, the colour on a variation image. That is the information the photograph was taken to carry, and text is the only way a shopper who cannot see it gets any of it.
Related guides
- How to Write WooCommerce Product Descriptions From Your Product Attributes: the same argument applied to product copy, where the fix is better inputs rather than better prompts.
- Best AI Product Description Plugins for WooCommerce (2026): an honest comparison of the description tools, including where rivals beat us.