Every image you add to a WordPress post has a field for alternative text, usually just called alt text. Many editors leave it empty. Others fill it with the file name, the word “image” or a string of keywords meant for search engines. Each of those choices fails the people alt text exists for: blind and low-vision visitors using screen readers, people with images turned off to save data and anyone whose images fail to load.
Writing good alt text isn’t difficult once you understand its purpose. It doesn’t need to be long or poetic. It needs to convey what the image contributes to the page, in a sentence or less. This guide explains the principles, gives examples for the situations WordPress editors encounter most and covers where to set alt text in WordPress.
What alt text is for
When a screen reader reaches an image, it reads the alt text aloud. If the alt text is missing, many screen readers read the file name instead, something like “IMG underscore 4 5 2 3 dot jpeg”, which is meaningless. If the alt text is empty on purpose, the screen reader skips the image entirely.
Alt text should give a screen reader user the same information or function that a sighted person gets from the image. That’s the key principle: describe the purpose, not just the pixels.
The core question
Before writing alt text, ask: why is this image on the page? What would be lost if it disappeared?
- If the image conveys information, describe that information.
- If the image is a link or button, describe what it does or where it goes.
- If the image is purely decorative, give it empty alt text so it’s ignored.
- If the image is complex, such as a chart, provide a short alt text plus a fuller description nearby.
Informative images
Most images in articles are informative. Describe what matters in context, briefly.
Example: a photo in a blog post about a team event
- Poor: “image1.jpg”
- Poor: “team”
- Better: “Our team planting saplings at the community garden in Kothrud”
Example: a screenshot in a tutorial
- Poor: “screenshot”
- Better: “WordPress Settings, Reading screen with ‘Discourage search engines from indexing this site’ unchecked”
The context matters. The same photo of a dog might need “Golden retriever puppy sitting on a red blanket” on a pet shop’s product page, but simply “Our office dog, Bruno” on a company’s team page.
Keep it concise
Alt text should usually be a short sentence. Screen reader users can’t skim alt text; they hear all of it. Long descriptions slow them down. A common guideline is to keep it under about 125 characters, though that’s a rule of thumb, not a requirement.
Don’t start with “Image of” or “Picture of”. Screen readers already announce that it’s an image. Get straight to the description.
Don’t repeat the caption or surrounding text
If an image has a caption that already describes it, or the paragraph next to it explains exactly what it shows, alt text can be shorter or focus on what the caption doesn’t say. Repeating the same text twice is tedious for screen reader users.
Decorative images
Some images add nothing informational: background textures, ornamental dividers, generic stock photos used purely for visual interest. These should have empty alt text, written in HTML as alt=””. The screen reader then skips them.
In WordPress, leaving the alt text field empty in the block editor results in an empty alt attribute, which is correct for decorative images. The important thing is that empty alt text is a deliberate choice, not an oversight.
Be honest about whether an image is decorative. A hero image showing your shop front conveys something about your business. A generic photo of a laptop on a desk at the top of a blog post usually doesn’t.
Images that are links
When an image is a link, its alt text becomes the link text. Describe the destination or action, not the image.
Example: a logo linking to the homepage
- Poor: “logo”
- Better: “Sharma Associates home”
Example: a social media icon
- Poor: “icon”
- Better: “Sharma Associates on Instagram”
Example: a product image linking to the product page
- Better: “Handwoven cotton table runner, indigo”
If the link also contains visible text describing the destination, the image can have empty alt text to avoid repetition.
Images containing text
If an image contains text, such as a quote graphic, a promotional banner or an infographic heading, include the text in the alt attribute. Better still, avoid putting important text in images at all, because it can’t be resized, translated or read by search engines as easily.
Example: a banner reading “Diwali Sale: 20% off all lamps until 3 November”
- Alt text: “Diwali Sale: 20% off all lamps until 3 November”
Charts, graphs and infographics
Complex images need two levels of description:
- A short alt text summarising the key point: “Bar chart showing website enquiries rising from 20 in January to 65 in June”
- A longer description or data table nearby, in the content, for people who need the details
The block editor makes it easy to add a table below a chart, which benefits everyone, not just screen reader users.
Product images
For online stores, product images are central to buying decisions. Alt text should help someone choose:
- Product type, colour, material, pattern and any distinguishing features
- For gallery images, what each one shows differently: “Back view showing zip closure”, “Close-up of embroidered collar”
Avoid simply repeating the product name on every image. Describe what each image adds.
Alt text and SEO
Alt text helps search engines understand images, which supports image search and the relevance of the page. But writing for SEO first leads to keyword stuffing, which is unhelpful for screen reader users and can be treated as spam. Write accurate, natural descriptions for people. If a relevant keyword fits naturally, fine. If it doesn’t, leave it out.
Where to set alt text in WordPress
In the block editor
Select an image block. In the block settings sidebar, find the “Alternative text” field. The text you enter there is used for that instance of the image.
In the media library
When you upload or edit an image in the media library, there’s an “Alternative Text” field. This value becomes the default for new uses of the image. Changing it in the media library doesn’t automatically update images already inserted in posts, which keep their own alt text.
Featured images
Featured images often take alt text from the media library value. Make sure important images, like product images and article hero images, have alt text set in the library.
Page builders and themes
Page builders and theme options often have their own image fields. Check that they output alt text, and set it in each widget where needed.
Fixing alt text across an existing site
On a large site, missing alt text can number in the thousands. Prioritise:
- Images that convey important information, such as product images and tutorial screenshots
- Images that are links, such as logos and icons
- Images on high-traffic pages
- Everything else, over time
Automated accessibility checkers like WAVE or axe can list images without alt attributes. Some plugins and AI tools suggest alt text automatically. They can help with volume, but review suggestions: automated descriptions often miss context and purpose.
Building the habit in your team
Alt text improves fastest when it becomes part of the normal publishing routine rather than a cleanup project. Add it to your pre-publish checklist, so no post goes live with informative images lacking descriptions. Show editors a few before-and-after examples from your own site. Some teams make it a rule that whoever adds an image writes its alt text at the same moment, because that’s when they know exactly why the image is there.
It also helps to agree on a few house conventions: how to describe team photos, how to handle product galleries, when logos need alt text and when they’re decorative. A one-page guide with examples answers most questions editors have and keeps descriptions consistent across the site.
Test by listening
The fastest way to judge alt text is to hear it. Turn on a screen reader, such as NVDA on Windows or VoiceOver on Mac and iPhone, and move through one of your pages. Within a minute, you’ll hear which descriptions help, which are missing and which are long or repetitive. Many editors find that one short listening session changes how they write alt text permanently.
Frequently asked questions
Should every image have alt text?
Every image should have an alt attribute. Informative images need descriptive text; decorative ones need it empty.
Can AI write my alt text?
AI can describe what’s in an image, which is a useful starting point. It doesn’t know why the image is on your page, so edit suggestions for context.
Is the title attribute a substitute for alt text?
No. The title attribute isn’t reliably read by screen readers and doesn’t replace alt text.
How long can alt text be?
There’s no strict limit, but aim for one concise sentence. For complex images, use a longer description in the content.
