Alt text: the practical guide, image by image
Alt text is the alt attribute of an image: the text a screen reader reads in its place, and the text that shows up when the image doesn't load.
This guide shows you what to write in it, and when to leave it empty, across sixteen example pages, from a bakery to a surf shop.
Decide image by image
#How do you know if an image needs alt text?
Put yourself in the shoes of someone listening to the page with a screen reader. They hear the image's alt, slipped into the middle of the surrounding text.
The whole method fits in one question: if the image disappeared, what would this person miss? Work through the four steps below in order.
- Is the image alone in a link or button, with no visible text next to it?
- Yes: write the destination or the action (see the examples). That's a filled alt.
- No: go to question 2.
- Does the image show text that appears nowhere else on the page?
- Yes: copy that text word for word (see the examples). That's a filled alt.
- No: go to question 3.
- Does the image show something the surrounding text doesn't say? A rating, for example, or what a product looks like.
- Yes: say it in one short sentence (see the examples). That's a filled alt.
- No: go to step 4.
- All that's left is decoration, or a repeat of nearby text.
- Leave the quotes empty (see the examples, then the cases where the same image changes role). That's an empty alt.
Still unsure? Read the page out loud to a colleague without showing them the screen.
Whatever you'd naturally say in place of the image is your alt. If you'd skip straight to the next paragraph, leave it empty.
#Two special cases
Two kinds of images need a little more than these four questions.
- A complex image (chart, diagram, map): the alt alone isn't enough. Write a short alt that says what the image shows and where to find the details, then put the full description on the page, right next to it: a table, a list, a paragraph (see the chart example).
- A CAPTCHA: the alt says what the image is for, never the code to type. And the page offers another way through, such as an audio version (see the example).
#How to write good alt text: six habits
You know the image needs an alt. Now you have to write it without letting it run long, and here are the situations you'll run into most often.
1. You're describing a construction photo for an article.
Keep the sentence you'd say over the phone, and nothing more: alt="Two carpenters put the roof on the new gym".
2. You're tempted to start with "Image of".
Cut those words, since the screen reader already announces an image: alt="Fishing boats in the harbor at sunset".
3. The image shows a sentence, like a sale banner.
Copy the sentence exactly, and leave out the font and colors: alt="30% off all coats".
4. An interactive element shows only an icon, with no text next to it.
Picture a button or link with just an arrow: the alt becomes its name, so say what the click does, alt="Next page", and definitely not "Right arrow".
5. You're posting a photo of someone you don't know.
Don't guess their gender, background or age. Name them if you know who they are; otherwise describe what they're doing, alt="Presenting in front of a screen full of charts".
6. Your site is available in several languages.
Write the alt in the language of the page: on the French version, the screen reader switches to a French voice and mangles any alt left in English. On the French page, it becomes alt="Le fournil vu depuis la rue".
#Decorative images: when the alt should stay empty
A decorative image is one whose absence would change nothing for the person listening. It gets alt="": two quotation marks with no space between them.
Don't confuse an empty alt with a missing one. Without the attribute, many screen readers read the file name, and your visitor hears "IMG 4021 dot jpg".
On a tea company's "Our story" page, a leafy border separates two paragraphs, and neither of them mentions it.
alt=""Why. Remove the border and the text tells the same story: it gives the page rhythm and does nothing else.
At a cabin rental company, a photo of a fjord sits behind a heading, a sentence and a "Book" button.
alt=""Why. The heading and the sentence already say what the photo shows, and the photo just sets the mood.
The habit of adding a descriptive alt everywhere "just to be safe" fills people's ears with noise. We cover it in a separate article.
Your images don't need alternative text
#Alt text for informative images: examples
An informative image carries something the text doesn't say. Its alt passes on that information and leaves out everything that's only there to look nice.
Ask yourself: "If I couldn't show this image, what words would I use?" You usually need far fewer than you think.
On a diner's home page, an illustrated banner is the only place that announces the Tuesday deal.
alt="Free milkshake on Tuesdays"Why. The deal is the information, so the milkshake glass and the retro lettering stay out of the alt.
In a trattoria's review block, five stars show the rating, which isn't written anywhere as a number.
alt="Rating: 4 out of 5"Why. The five files make up a single piece of information: the first star carries it, and the other four stay silent.
Without this trick, the person hears "star, star, star, star, empty star" and has to count for themselves.
A cooperative's annual report shows its maple syrup production as a bar chart, followed by a table, with no figures in the text.
alt="Syrup production from 2021 to 2025: from 48 to 80 tonnes, with a dip in 2023. Details in the table below."Why. The alt sums up the trend in one sentence and points to the table, which holds the details.
Remember this pair for any chart, map or diagram: a short alt that gives the takeaway, and a full description visible right next to it.
#Alt text for clickable images in links and buttons
When an image is the only content of a link or button, its alt becomes the name of that link. The screen reader announces "Search, button" or "Home, link", and the person decides whether to click based on that alone.
For developers, this is the most common case: the mockup shows an icon with no label. Write what the click does.
On a tram network's website, the search button shows only a magnifying glass.
alt="Search"Why. With alt="magnifying glass", you'd hear "magnifying glass, button", and nobody knows what a magnifying glass does on a tram website.
A hammam booking form asks you to type a distorted code, with a button to listen to it.
alt="Verification code to enter"Why. The alt says what the image is for and never gives the code itself, or any bot could read it.
In a bakery's header, the logo sits alone in the link back to the home page.
alt="Maison Aubépine, home"Why. Alone in the link, the logo says who you are and where the click goes, and the word "logo" would add nothing.
On a recipe site, a row of round avatars links to the contributors' profiles, with no names shown.
alt="Ilse van Dorp"Why. The avatar serves as the link's name: it names the person, and what they look like doesn't matter here.
On mobile, a surfboard shop shrinks its cart down to an icon topped with a "3" badge.
alt="Cart, 3 items"Why. The alt gives the destination and the number of items, and the badge is hidden so the number isn't read twice.
#Alt text examples: the same image on different pages
Here's the trap content writers fall into most: you enter the alt once in the CMS media library, and it follows the image everywhere. Yet the right alt depends on where the image appears, and the file knows nothing about that.
That's why the tool at the top of this page accepts, along with the image, a screenshot of the area around it or the HTML code around it. With that context, it does a better job of recognizing the image type (decorative, informative, interactive, complex or captcha) and suggests text you can edit before you copy it.
Each of the five pairs below uses the same file on two different sites.
#The logo: home link or article thumbnail
The Maison Aubépine logo, shown earlier in its home link, turns up again in a local paper announcing the bakery's second shop.
alt=""Why. The article headline already names the bakery: here, the logo is just a thumbnail.
#The product photo: product page or clickable card
On Atelier Kōyō's product page, the photo is the only thing that shows what the teapot looks like, since the text covers the price, capacity and care.
alt="Brown stoneware teapot, woven bamboo handle, green glaze dripping down the shoulder"Why. The alt gives what a sighted shopper takes in and the text leaves out: the material, the handle and the glaze.
The same photo then appears as a thumbnail in a gift guide, where each card is a single link with the name, the studio and the price.
alt=""Why. The product name is already in the link, so an alt would make people hear it twice in a row.
#The portrait: team card or lone avatar
On an architecture firm's team page, Ilse van Dorp's name and role are written right under her photo.
alt=""Why. The text already says who she is, and describing her face would only add guesswork.
Earlier, the same photo, shrunk to an avatar, was alone in a profile link. There, it got her name: alt="Ilse van Dorp".
One exception to keep in mind: emotion. If the person looks furious or delighted and that changes how the article reads, say so in the alt.
#The chart: only source or repeat of the text
The cooperative's chart, shown earlier with its summary alt, also illustrates a specialty food shop's article whose paragraph already gives every value.
alt=""Why. The paragraph right above already gives every figure the image repeats.
#The icon: marker next to text or the link's name
An online olive oil shop shows a cart icon followed by the visible text "Cart (3)".
alt=""Why. With an alt, you'd hear "cart, cart, 3": the icon stays quiet and lets the text speak.
Compare it with the surf shop from earlier. There, the same icon, alone in its link, has alt="Cart, 3 items".
The table below brings the five pairs together.
| Image | Context | Example alt text |
|---|---|---|
| Logo | Alone in the link to the home page | alt="Maison Aubépine, home" |
| Thumbnail in an article whose text already names the brand | alt="" | |
| Product photo | Product page, where only the photo shows what it looks like | alt="Brown stoneware teapot, woven bamboo handle, green glaze dripping down the shoulder" |
| Clickable card that already contains the product name | alt="" | |
| Portrait | Avatar alone in a link to a profile | alt="Ilse van Dorp" |
| Team card with the name and role written below | alt="" | |
| Chart | Page where no text gives the figures | alt="Syrup production from 2021 to 2025: from 48 to 80 tonnes, with a dip in 2023. Details in the table below." |
| Page whose text already gives every value | alt="" | |
| Cart icon | Alone in a link | alt="Cart, 3 items" |
| Followed by visible text that says the same thing | alt="" |
Does your CMS only let you enter the alt in the media library? Ask your tech team to make it editable at the block level too.
#Nine common alt text mistakes and how to fix them
Mistakes fall into two groups. Either you get the image's role wrong, or you get the role right and the text misses the mark.
First group: getting the image type wrong. These mistakes happen before you even start writing.
#A decorative image mistaken for an informative one
Your blog theme inserts a floral border between every block of the article.
Avoid: alt="Green floral border"
Correct: alt=""
Repeated ten times a page, "green floral border" interrupts the reading and teaches nobody anything.
#A logo link mistaken for decoration
In the header, you empty the logo's alt because "it's just a logo".
Avoid: alt=""
Correct: alt="Maison Aubépine, home"
Alone in the link, the logo is the link's name: empty it and the link goes silent.
#A chart treated like an illustration
Your report shows a sales chart that the text doesn't discuss.
Avoid: alt="Colorful bar chart"
Correct: alt="Sales 2025: up from March to August, then down through December. Details in the table below."
The person listening wants the data, and the shape of the bars does nothing for them.
Second group: writing the alt badly. The type is right, but the text doesn't help.
#Starting with "Image of"
You're illustrating an article about the port of Sète.
Avoid: alt="Image of the port of Sète"
Correct: alt="Trawlers moored at the quay in the port of Sète"
The screen reader already announces an image, so lead with what matters.
#Leaving the file name as is
Your CMS prefilled the field with the name of the uploaded file.
Avoid: alt="IMG_4021.jpg"
Correct: alt="Wooden cabin on the edge of a fjord"
A file name means nothing to anyone: replace it, or clear the field if the image is decorative.
#Describing the look instead of the action
A lone arrow links to the next page of an article list.
Avoid: alt="Blue right arrow"
Correct: alt="Next page"
In a link, people want to know where they're going, and the arrow's color doesn't help them one bit.
#Summarizing the text in the image
A banner reads "Free shipping on orders over $40 until June 15".
Avoid: alt="Promotional banner"
Correct: alt="Free shipping on orders over $40 until June 15"
Without the exact wording, the offer vanishes for anyone listening to the page.
#Stacking keywords
On a product page, you think adding keywords will help your SEO.
Avoid: alt="japanese teapot cast iron teapot gift cheap tea"
Correct: alt="Brown stoneware teapot, woven bamboo handle"
A list of keywords wears out the person listening, and Google treats it as filler.
#Guessing who the person is
For a trade show recap, you're describing a photo of a speaker.
Avoid: alt="Smiling young Asian woman"
Correct: alt="Dana Reed, head of sales, presents the results at the mic"
Nobody can tell someone's age or background by looking at them: name the person and say what they're doing.
#Checklist to check your images' alt text
Run every image on the page through these eight boxes.
To check a page that's already live, the Includdy app scans it and flags images with no alt. You'll then know which ones to rework with the checklist above.