Writing Alt Text That Actually Describes the Image
The checker can tell you an alt attribute is missing, is a filename or is 300 characters long. It cannot tell you whether "woman smiling" is the right description. That part is yours, and this page is the short version of how to do it.
The Question to Ask First
Before writing anything, ask: if this image vanished, what would the reader lose? If the answer is nothing, the image is decorative and the alt is empty. If the answer is information (a product, a chart, a face, a diagram), the alt text is that information, in the words you would use to describe it over the phone. If the answer is "the way to the next page" because the image is a link, the alt text is the destination. Most alt text problems come from skipping this question and describing pixels instead of purpose.
By Kind of Image
Photographs
Say what is in it that matters here. On a recipe page a photo gets "sliced lemon tart on a white plate"; on a page about the photographer it gets "lemon tart photographed with soft window light". The same image, two purposes, two alts. Skip "photo of", skip the camera settings, skip the mood words unless the mood is the point.
Product images
Name the product and the variant the image shows: "Trailhead 40 backpack in forest green, front view". Colour, angle and model matter because shoppers compare thumbnails. Do not repeat the price or the marketing line; the page already has those.
Charts and diagrams
State the conclusion, not the axes: "line chart: monthly signups rose from 1,200 in January to 4,800 in June". If the chart carries more than one sentence of information, put the alt as a one-line summary and the full data in a table or in the text below, then say so in the alt.
Logos
The company name, and nothing about the logo's design: alt="Acme". If the logo links home, alt="Acme home". If the logo appears next to the company name in text, it is decorative: alt="".
Icons
An icon next to a label is decorative (the label does the work). An icon on its own, in a button or link, is the label: the magnifier gets alt="Search", the envelope gets alt="Email us". Inline SVG icons follow the same rule with aria-hidden="true" for decorative ones and aria-label on the control for meaningful ones.
Screenshots
Describe what the screenshot demonstrates, not the interface in general: "the Settings page with Two-factor authentication switched on". If the screenshot contains text the reader needs, that text goes in the alt or, if it is long, in the paragraph next to it.
Images of text
The alt is the text. A banner reading "Free shipping over $50" gets exactly that as alt. Better still, make it real text.
Linked images
The alt becomes the link's name, so it describes the destination: a thumbnail linking to an article gets the article title. A linked image with alt="" produces a link with no name, which the checker marks as an error because screen reader users hear only "link".
The Rules the Checker Applies
| Finding | Why it matters | Fix |
|---|---|---|
| No alt attribute | Screen readers may read the filename; search engines get nothing. | Add alt with a description, or alt="" if decorative. |
| Alt is a filename (IMG_4032, hero-banner.jpg) | Announced as gibberish; the CMS filled it in automatically. | Replace with a description. |
| Generic alt (image, logo, icon) | Says what the element is, not what it shows. | Say what it shows or what it does. |
| Starts with "image of" or "picture of" | Redundant: the role is already announced. | Delete the prefix. |
| Over 125 characters | Screen readers may truncate; the description belongs in the text. | Shorten; move detail to a figcaption or paragraph. |
| Decorative image is the only content of a link | The link has no accessible name. | Give the image an alt naming the destination. |
| Alt equals the figcaption | The reader hears it twice. | Make the alt describe, the caption explain. |
| Same alt on different images | Usually a template default. | Describe each one, or mark true duplicates decorative. |
| Alt on a linked image says "click here" | The link name does not say where it goes. | Name the destination. |
Beyond the Alt Attribute
Two attributes that are not alt but travel with it. width and height let the browser reserve the right space before the image arrives, so the text does not jump when it loads; they should be on every img, including responsive ones (the browser uses them for the aspect ratio). loading="lazy" defers images below the fold and should not be on the first one or two, which need to load immediately; give the hero fetchpriority="high" instead. In URL mode the checker also fetches each image and reports files over 300 KB, wrong content types and broken links, because a perfect alt on a 404 helps nobody.
Questions People Ask About Alt Text
What is alt text?
Alt text is the alt attribute on an img element: a short description of the image that screen readers read aloud, browsers show when the image fails to load, and search engines use to understand what the image is. It is the only way an image can be understood by someone who cannot see it.
When should alt text be empty?
When the image adds nothing a sighted reader needs: a decorative flourish, a background texture, a spacer, or an icon next to text that already says the same thing. Write alt="" (present but empty) so screen readers skip it. Leaving the attribute out entirely is not the same; then the filename may be read instead.
How long should alt text be?
As long as it needs to be and no longer; most good alt text is between three and fifteen words. Screen readers typically stop reading around 125 characters, so anything longer belongs in the surrounding text or a figcaption.
Should alt text start with "image of" or "picture of"?
No. Screen readers already announce the element as an image, so the prefix is read as "image, image of a red bicycle". Start with the content: "red bicycle leaning against a brick wall".
Does alt text help SEO?
Yes, in two ways. It is the main text signal for image search, and it is part of the page content for regular search. Describe the image honestly; stuffing keywords into alt text is read as spam by both search engines and screen reader users.
What alt text does a linked image need?
The alt text becomes the link text, so it must say where the link goes, not what the picture shows. A logo that links home gets alt="Company name home page"; a product thumbnail that links to the product gets the product name.