Fixing Missing or Wrong Alt Text
Alt text is the short written alternative for an image that a screen reader speaks aloud, that shows when an image fails to load, and that search engines and AI tools read to understand what the picture adds.
When it is missing, a blind visitor may hear a file name such as "IMG underscore 4471 dot jpeg", or nothing at all. When it is wrong, they hear words that do not match the page. This guide explains which images need a description and which need an empty alt, how to write each kind, and how to fix a whole site without rewriting every page by hand.
What WCAG 1.1.1 actually asks for
WCAG success criterion 1.1.1, Non-text Content, is at level A, the most basic level. It says that anything shown to sighted people as a picture, icon, chart or other non-text content needs a text alternative that serves the same purpose. The key word is purpose. The criterion does not ask you to describe how an image looks in detail; it asks you to give a non-sighted visitor whatever the image gives everyone else.
In HTML that text alternative is usually the alt attribute on an <img>.
It is also needed on <area> elements in image maps and on <input type="image">
buttons. Inline SVG, icon fonts and CSS background images have no alt attribute at all, so they need
a different technique, covered further down.
Three states of the attribute behave very differently:
| Markup | What a screen reader typically does | When it is right |
|---|---|---|
<img src="team.jpg"> (no alt) | Announces it as an image and often reads the file name or address instead. | Never. This is the failure the checker reports most. |
<img src="swirl.png" alt=""> | Skips the image entirely, as if it were not there. | Decorative images, and images whose meaning is already in nearby text. |
<img src="team.jpg" alt="Four staff standing outside the Leeds workshop"> | Announces "image" or "graphic" followed by the text. | Images that carry information the page needs. |
Notice that screen readers already say "image" or "graphic". That is why alt text should not start with "image of" or "picture of": the visitor hears the word twice.
alt=" ", is not the same as an empty alt.
Some tools treat it as present text. Use two quotes with nothing between them.Five kinds of image and what each needs
Almost every image on a small business site falls into one of these groups. Decide the group first; the right alt text usually follows.
Informative images
Photos and illustrations that show something the text does not already say: what a product looks like, the finished result of a job, the location of an entrance. Write one or two plain sentences that give the same information. For a product photo, mention what a buyer would want to know and cannot read elsewhere, such as the colour, the finish or what is included.
Functional images
An image that is the only content of a link or a button: a logo linking to the home page, a magnifying
glass that submits a search, a printer icon. Here the alt text describes where the link goes or what
the button does, not what the picture looks like. A logo linking home becomes alt="Brightwater Plumbing home",
not "blue water drop logo". A basket icon becomes alt="Basket, 2 items" if the count is
shown visually.
Images of text
Banners, quote graphics and sale badges where the words are part of the picture. The alt text must repeat those words. WCAG 1.4.5 at level AA also asks you to use real text rather than pictures of text wherever you can, so the better long-term fix is live text laid over a background image.
Complex images
Charts, graphs, maps and diagrams hold more information than a short alt can carry. Give a short alt
that says what the image is and its main point, such as alt="Bar chart: enquiries doubled between January and June",
then provide the full data nearby as a table, a list or a paragraph, or in a <details>
element under the chart.
Decorative images
Background textures, dividers, stock photos used only for mood, and icons placed beside a text label
that already says the same thing. These get alt="" so screen readers skip them. If you are
unsure, ask whether a visitor who cannot see the image would miss anything. If the answer is no, it is
decorative.
Writing alt text that helps
Good alt text is shaped by the page it sits on. The same photo of a café counter might need alt="Counter with trays of fresh pastries"
on a menu page and alt="Step-free entrance with automatic door, leading straight to the counter"
on an accessibility information page. Write for the reason the image is there.
- Lead with what matters. Screen reader users can stop listening at any time, so put the key detail first.
- Keep it short, but not artificially short. WCAG sets no character limit. A sentence or two is usually enough. If you need more, the content belongs in visible text.
- Do not repeat the caption. If a
<figcaption>already describes the image fully, the alt can be empty or add only what the caption leaves out. - Skip keyword lists. Alt text stuffed with search phrases is irritating to listen to and does not help rankings. Describe the image honestly and the right words appear naturally.
- Use proper punctuation. A full stop at the end gives screen readers a natural pause before the next item.
- Name people only where it matters. On a team page, the person's name and role is what the visitor needs. For a crowd at an event, "Around thirty people at the spring open day" is enough.
Before and after
| Weak alt text | Why it fails | Better |
|---|---|---|
DSC_0192.jpg | A file name, usually added automatically by the CMS. | Oak dining table with six matching chairs |
image | Says nothing the screen reader has not already said. | Describe
it, or use alt="" if it is decorative. |
best cheap boiler repair Chesterfield boiler service | Keyword stuffing that describes nothing. | Engineer checking the pressure gauge on a wall-mounted boiler |
logo on a home link | Describes the picture, not where the link goes. | Brightwater Plumbing home |
Chart | Hides the point the chart makes. | Line chart: bookings rise each month from March to August,
plus the figures in a table below |
SVG, icon fonts and background images
Modern sites draw many images without an <img> element, and these are the ones people forget.
Inline SVG
An informative inline SVG needs role="img" and a name. A <title> as
the first child is widely supported; adding aria-labelledby pointing at it makes the link
explicit. A decorative SVG, including an icon next to a visible text label, should be hidden with aria-hidden="true",
and focusable="false" stops very old browsers putting it in the tab order.
<!-- Informative -->
<svg role="img" aria-labelledby="rating-title" viewBox="0 0 100 20">
<title id="rating-title">Rated 4 out of 5</title>
...
</svg>
<!-- Decorative, beside a visible label -->
<button type="button">
<svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">...</svg>
Download price list
</button>Icon fonts
Icon fonts draw icons with private-use characters that screen readers may read as nonsense or silence.
Hide the icon element with aria-hidden="true", then give the link or button a name, either
with visible text or with a visually hidden span.
CSS background images
A background image set in CSS has no alternative text and screen readers ignore it. That is fine for
decoration. If a background image carries meaning, such as a hero photo with words baked in, either move
the words into real text or change the image to an <img> with proper alt text.
role="img" and aria-label to a <div>
with a background image just to silence the checker unless the image genuinely carries information. Adding
names to decoration makes pages noisier, not more accessible.The fix, step by step
Step 1
List every image the checker flagged
Run the Accessibility Audit on the page and note each image reported under non-text content, with its file name and where it sits. Then run it on one page of each template, such as a product page, a blog post and the home page, because many missing alt attributes come from the theme rather than from content. Group the findings into template images, which you fix once in code, and content images, which live in the media library or in individual pages.
Step 2
Decide what job each image does
For every flagged image, decide whether it is informative, functional, an image of text, a complex chart or diagram, or decorative. Look at the image in its context rather than on its own, because the same file can be informative on one page and decorative on another. Write the category next to each item in your list. This single decision prevents most bad alt text, because it tells you whether to describe the picture, describe an action, or leave it empty.
Step 3
Write alt text for informative images
For each informative image, write one or two plain sentences giving the information the image adds to that page, most important detail first. Leave out words like image of or photo of, because screen readers already announce an image. Do not repeat a caption or heading that sits right next to it. For charts, write a short summary in the alt and put the full data in a table or paragraph directly below, so everyone can read the figures.
Step 4
Give linked images and icon buttons a purpose
Find every link or button whose only content is an image or icon, such as the header
logo, social icons, a search button and a basket icon. Set the alt text, or the aria-label
on the button when the icon is an SVG or font icon, to describe the destination or action: Home,
Search, Follow us on Instagram. If the link already contains visible text next
to the image, make the image alt empty so the name is not read twice.
Step 5
Mark decorative images with an empty alt
Give every decorative image an empty attribute written as alt="", with
nothing between the quotes, rather than removing the attribute. For inline SVG decoration add aria-hidden="true"
and focusable="false". Check your theme for spacer images, divider graphics and background
shapes that still have no alt. Do not mark something decorative just to clear a finding quickly: if a
visitor would lose information without the image, it needs a description.
Step 6
Fix the source templates and media library
Change the theme or component code so every <img> outputs the alt text
stored with the image, with a sensible fallback such as the product name, and never an empty attribute
by accident. Then update alt text in the media library for images reused across pages. In WordPress,
remember that images already placed in posts keep the alt they had when inserted, so edit those posts
too. Finally make alt text a required field in your upload or publishing checklist.
Step 7
Listen to the page with a screen reader
Turn on NVDA on Windows or VoiceOver on a Mac and move through the page image by image. In NVDA the G key jumps to the next graphic; on a Mac the VoiceOver rotor lists images. Listen for file names, repeated phrases, logos described by colour instead of purpose, and decorative images that are still announced. Then run the Accessibility Audit again to confirm the non-text content findings have cleared on every template you changed.
Fixing alt text on common platforms
WordPress
Each image in the Media Library has an Alternative Text field. The block editor copies that value into the Image block when you insert the image, and stores it in the post itself. That has a practical consequence: editing the alt in the Media Library later does not change posts where the image is already placed. To fix an existing post, select the Image block and edit Alternative text in the block settings sidebar. Featured images are usually output by the theme using the Media Library value, so fixing the library does fix those. Some page builders store their own alt per widget, so check the builder's image settings too.
If your theme outputs images with no alt at all, look for template code that builds <img>
tags by hand instead of using wp_get_attachment_image() or the_post_thumbnail(),
which include the stored alt text automatically.
Shopify
Product images take alt text from the media item: open the product, select the image and choose the
option to add alt text. Images in the Files area of the admin have their own alt field. In theme code,
the image_tag filter outputs the image's stored alt; you can pass a fallback, for example
{{ image | image_url: width: 800 | image_tag: alt: image.alt | default: product.title }},
adjusted to your theme's own markup. Check sections added by apps, such as review widgets and upsell
carousels, as they often produce their own images.
Custom sites and frameworks
In React and Next.js, make alt a required prop on your image component so a missing value
fails type checking. The Next.js Image component already requires an alt prop,
and an empty string is accepted for decorative images. The jsx-a11y/alt-text ESLint rule
catches <img> elements without alt during development. In a headless CMS, make the
alt field on the image or asset model required, and allow editors to tick a "decorative" box that outputs
an empty alt.
Edge cases the checker may not judge
- AI-generated alt text. Many CMSs and plugins can now suggest alt text automatically. It is a useful starting point, but it describes what is in the picture, not why it is on your page, and it can be confidently wrong. Review every suggestion before publishing.
- Alt text that exists but is wrong. An automated checker can confirm an alt attribute is present and not obviously a file name; it cannot tell whether "Red jumper" describes a photo of blue trainers. Spot-check templates where alt text is filled automatically from product names or titles.
- Carousels and galleries. Each slide image needs its own alt. Duplicated alt text on every slide, often the product name repeated, gives screen reader users no reason to look through them.
- Images inside links with text. A card with a photo, a heading and a "view" link often wraps all three in one link. Give the photo an empty alt so the link name is the heading rather than the heading plus a photo description.
- CAPTCHAs and tests. WCAG allows the alt to identify the purpose of a test without giving away the answer, but an alternative way to pass the test must also be provided.
- Emoji and symbols in text. These are read aloud by their names, which can be long.
A row of decorative emoji between sections can be wrapped in a span with
aria-hidden="true".
Stopping missing alt text coming back
Alt text problems return whenever someone uploads an image in a hurry. A few habits keep them away:
- Add "alt text written or marked decorative" to the checklist for every new page, post and product.
- Make the alt field required in your CMS or asset model where the platform allows it.
- Give editors a short house style: lead with what matters, no "image of", no keyword lists, describe purpose for links.
- Add an automated check to your build or deployment, such as the ESLint rule for React projects or an accessibility test in your test suite.
- Run the Accessibility Audit after theme updates and after installing any plugin or app that adds images, sliders or widgets.
For wider context on how images fit into an accessible page, see the Accessibility Guide. If an image is inside a link, the link text guide explains how the alt becomes the link's name.
1. Is it better to leave alt text out or leave it empty?
Leave it empty, never out. An img element with no alt attribute tells assistive technology nothing, so many screen readers fall back to reading the file name or the image address, which is meaningless noise. An empty alt, written as two quotation marks with nothing between them, is a deliberate signal that the image is decorative and can be skipped. The Accessibility Audit reports a missing alt attribute as a failure, but it accepts an empty alt as a valid choice.
2. How long should alt text be?
WCAG does not set a maximum length, and there is no single number that fits every image. For most photos one short sentence is enough, and two sentences is plenty. Screen reader users cannot skim alt text the way sighted people skim a page, so every extra word costs them time. If an image needs a paragraph or more to explain, such as a detailed chart, give it a short alt and put the full explanation in visible text beside or below it.
3. Should alt text include keywords for SEO?
Only where they describe the image honestly. Search engines use alt text to understand images, so an accurate description that naturally uses the product name or service helps. A list of search phrases does not describe anything, frustrates screen reader users and can be treated as keyword stuffing. Write for the person who cannot see the picture first. A clear, specific description almost always contains the words someone would search for anyway, without needing to force them in.
4. What alt text should a logo have?
It depends on what the logo does. A logo that links to the home page is a functional image, so its alt text should say where the link goes, usually the business name followed by home, such as Brightwater Plumbing home. A logo shown without a link, for example on an about page, can simply use the business name. A row of client or partner logos should name each company. Avoid descriptions of the logo design itself unless the design is the subject.
5. Do product images in a shop need different alt text from each other?
Yes. If every image in a product gallery has the same alt text, usually the product name, a screen reader user hears the same words several times and learns nothing about the differences. Describe what each view shows: the front, the back, the label, the item in use, or a close-up of the fabric. The first image can include the product name, and the others can focus on what that particular photo adds to the listing.
6. Can I use the title attribute instead of alt?
No. The title attribute shows a tooltip on mouse hover in some browsers, but it is not reliably read by screen readers, is not shown on touch screens, and is not a substitute for alt under WCAG. Some accessibility tools fall back to it when alt is missing, which is why a checker might not flag it, but you should not depend on that. Put the text alternative in the alt attribute and leave title off images unless it adds something extra.
7. Does a caption count as alt text?
A visible caption helps everyone and is read by screen readers as normal text, but it does not replace the alt attribute. If the caption already fully describes what the image shows, the image can take an empty alt so the same information is not heard twice. If the caption only gives a credit or a date, the alt still needs to describe the image. Wrapping both in figure and figcaption elements keeps the relationship between image and caption clear.
The Accessibility Audit tests your page against WCAG 2.2 level AA and lists each finding, including images with no text alternative, with the element that failed and the success criterion behind it.
Open Accessibility Fixes →