- alt text
- WCAG
- accessibility
- how-to
How to Write Good Alt Text for Your Website Images
A plain-English guide to alt text: what it is, how to write it for photos, logos, links and decorative images, and common mistakes to avoid.
On this page
Alt text is a short written description of an image, stored in your website's code. People who are blind or have low vision often use screen readers, software that reads the page aloud. When a screen reader reaches an image, it reads the alt text. If there isn't any, the visitor may hear a file name like "IMG_4021.jpg," or nothing at all.
Missing alt text is one of the most common problems on the web. The WebAIM Million report lists missing alternative text among the most frequently detected accessibility failures on home pages. The good news: it is also one of the easiest problems to fix, and you don't need to be a developer to write it.
This is not legal advice. Good alt text makes your site more usable, but no single fix guarantees compliance or prevents a legal claim. If you have received a demand letter, talk to an attorney.
What the standard says
The Web Content Accessibility Guidelines (WCAG) cover this in success criterion 1.1.1, Non-text Content (Level A). WCAG 2.1 says: "All non-text content that is presented to the user has a text alternative that serves the equivalent purpose," with a few exceptions, such as purely decorative images.
The key words are equivalent purpose. Alt text isn't about describing every pixel. It is about giving a screen reader user the same information or function a sighted visitor gets from the image.
The Justice Department's web accessibility guidance puts it simply: "To be useful, the text should be short and descriptive."
How alt text looks in code
Alt text lives in the alt attribute of an image tag. Most website builders (WordPress, Shopify, Squarespace, Wix and others) have an "alt text" or "image description" field, so you can usually add it without touching code.
<img src="IMG_4021.jpg" alt="Golden retriever getting a bath at our grooming station">
Ask one question first: what is this image for?
The W3C has an alt text decision tree that walks through this. The short version: the right alt text depends on what job the image is doing on the page.
Informative images: describe what matters
For photos and simple graphics that add information, describe what a visitor needs to know. WebAIM's alt text guide says alt text should be "accurate and equivalent in representing content and function," and that "only a few words are necessary, though rarely a short sentence or two may be appropriate."
<!-- Too vague -->
<img src="cake.jpg" alt="cake">
<!-- Better -->
<img src="cake.jpg" alt="Three-tier vanilla wedding cake decorated with fresh roses">
Images that are links or buttons: describe the action
If an image is the only thing inside a link or button, the alt text needs to say where the link goes or what the button does. WebAIM notes that in this case, alt text "is all that a screen reader has to go on," and that empty alt text "would never be appropriate here."
<!-- Before: the visitor hears the file name or nothing -->
<a href="/cart"><img src="cart-icon.png"></a>
<!-- After: the visitor hears where the link goes -->
<a href="/cart"><img src="cart-icon.png" alt="Shopping cart"></a>
Skip phrases like "link to" or "click here for." WebAIM points out that screen readers already announce that it's a link.
Images of text: include the text
If an image contains words, such as a sale banner or a scanned flyer, the W3C decision tree says to "use the alt attribute to include the text of the image." Better still, use real text on the page instead of a picture of text.
<img src="sale-banner.png" alt="Spring sale: 20% off all houseplants through April 30">
Logos
A logo usually works as your business name, so use the name. If the logo links to your homepage, say so.
<a href="/"><img src="logo.svg" alt="Maple Street Bakery home"></a>
Decorative images: leave alt empty
Some images are pure decoration: background textures, dividers, or a stock photo that adds mood but no information. For these, the W3C decision tree says: "Use an empty alt attribute." That tells screen readers to skip the image.
<img src="divider-flourish.png" alt="">
Empty is not the same as missing. alt="" means "skip this." No alt at all means the screen reader has to guess, and it may read the file name.
Charts and complex images
A short alt text can't hold all the data in a chart. Give it a brief alt text that names what it is, and put the key information in the text or a table on the page, as the W3C decision tree recommends.
Context changes the right answer
The same photo can need different alt text on different pages. WebAIM notes that "algorithms alone cannot understand what an image means within the context of the overall page."
Take a photo of your storefront:
- On your Contact page, where you're helping people find you: "Red brick storefront with a green awning at 112 Main Street."
- On your About page, next to a paragraph that already describes the shop: it may add nothing new, so
alt=""could be right.
Ask yourself: "If I couldn't see this image, what would I need to know here?"
Common mistakes to avoid
- Starting with "image of" or "picture of." WebAIM calls these phrases redundant, since screen readers already announce that it's an image.
- Using the file name. "DSC_0042.jpg" tells nobody anything.
- Stuffing keywords. "Best bakery cakes cupcakes cookies Springfield bakery" is written for search engines, not people, and it makes the page harder to use.
- Repeating nearby text. If the caption right below says the same thing, the visitor hears it twice. Consider
alt=""for the image. - Writing an essay. Keep it to what matters on that page.
- Leaving alt off "unimportant" images. If it really is decorative, use
alt="". Don't leave the attribute out.
A note on automatic alt text
Some tools now generate alt text automatically. They can be a starting point, but review every suggestion. A tool can tell you there's a dog in the photo. It can't know that the point of the image is to show your new grooming station.
How to find images missing alt text
You probably have more images than you think: product photos, staff headshots, icons, logos and banners. An automated scanner can quickly find images that have no alt attribute at all. What a scanner can't do is judge whether existing alt text is accurate or useful. That part takes a human reading through the page.
Run a free scan of your homepage to see which images are missing alt text, along with other detectable problems.
For more quick wins, read The 10 Most Common Website Accessibility Problems (and How to Fix Them). If you're wondering how much this kind of work costs, see How Much Does It Cost to Make a Website ADA Compliant?
If a demand letter mentioned missing image descriptions on your site, the Demand Letter Response Kit gives you a full scan of up to 5 pages, a dated PDF report for your attorney, and a fix guide your web person can follow.