How to write alt text that actually helps

Alt text is the short description in an image’s alt attribute. Screen readers read it aloud, browsers show it when the image fails to load, and search engines use it to work out what the picture shows. Missing alt text is one of the most common problems accessibility checkers find. And when alt text is there, it’s often too long, too vague, or about the wrong thing.

Start with one question: what is this image doing here?

Good alt text depends on what the image is doing on the page. The same photo can need three different descriptions on three different pages. So before you write anything, ask what it’s there for.

Most images fall into one of four groups:

• Decorative. It adds mood or fills space. Removing it would lose nothing.
• Informative. It shows something the text does not say.
• Functional. It is a link or a button. Clicking it does something.
• Complex. A chart, a diagram, a map, or a screenshot with a lot going on.

Each group gets a different treatment.

Decorative images get an empty alt

If the image adds nothing a reader needs, give it an empty alt attribute:

<img src="divider.svg" alt="" />

That is not the same as leaving the attribute out. With alt="", screen readers skip the image entirely. With no alt attribute at all, many screen readers fall back to the file name, so a visitor hears “I M G underscore 4 2 7 1 dot J P G” in the middle of your page.

Typical decorative images:

• Flourishes, dividers and background textures
• A stock photo next to a heading that already says the same thing
• An icon sitting beside a text label that already explains it
• Spacer images in old email templates

If you can move the image into CSS as a background, do that. CSS backgrounds need no alt text, and they stay out of the reading order altogether.

Informative images: describe what matters, briefly

For an image that carries meaning, write what a sighted visitor takes from it. A few rules keep this short and useful.

Do not start with “image of” or “picture of”. Screen readers already announce that it is an image. “Image of a woman reading on a phone” comes out as “Image, image of a woman reading on a phone.”

Keep it under about 125 characters. No standard sets this number. It comes from how some older screen readers handled long descriptions, and it is still a good discipline. If you need more than that, the detail belongs in the page text, not in the attribute.

Describe for the context. Take a photo of a woman reading on her phone in a garden. On a page about outdoor furniture, the alt might be “Woman reading on a wooden garden bench under a maple tree.” On a page about the widget’s Reading Mask, the same photo might be “Woman reading a long article on her phone with the Reading Mask turned on.” Same image, different purpose, different alt.

End with a period. It makes the screen reader pause naturally before moving to the next element.

Do not repeat the caption. If a visible caption already says it all, the alt can be short or, in some cases, empty.

Product photos: color, material and shape

Product images are where small shops lose the most. The product name is usually right next to the photo, so the alt text should add what the photo shows and the name does not: color, material, shape, and the angle you are looking from.

Compare these for the same listing:

• Weak: “Vase”
• Weak in a different way: “Blue vase ceramic handmade vase for flowers home decor gift”
• Good: “Slim blue glazed ceramic bud vase with a narrow neck, on a white background.”

The first says nothing. The second is written for a search engine and is miserable to listen to. The third tells a shopper who cannot see the photo what they would otherwise learn from it.

For galleries with several photos of one product, make each alt say what is different: “Side view of the rattan pendant lamp, showing the woven shade.” “Close-up of the shell chair seat, molded in off-white plastic.” Repeating the product name five times helps no one.

If you have hundreds or thousands of product photos, you will not write every alt by hand. This is where generated drafts earn their keep. Accessora’s AI alt text, on the Growth and Enterprise plans, writes an English first draft for each image that has none, and you can edit any of them. In the Shopify app, the drafts can go straight into your product media. Review the drafts for your bestsellers and hero images first, then spot-check the rest.

Functional images: describe the action, not the picture

When an image sits inside a link or a button, the alt text becomes the link text. So describe where the link goes or what the button does, not what the image looks like.

• A logo in the header that links home: alt="Accessora home", not alt="Blue logo with a smiling robot".
• A magnifying glass that submits a search: alt="Search".
• A trash can icon on a row: alt="Delete this address".
• A product photo that links to the product page: the product name works well here, because that is what the link is.

The test is simple. Pull up a list of all the links on the page, as screen reader users often do, and ask whether each one makes sense on its own. “Search”, “Delete this address” and “Accessora home” do. “Icon” and “arrow” do not.

If the icon is an inline SVG rather than an img, the same idea applies: give the button an accessible name with visible text or an aria-label. Missing names on icon-only buttons are one of the problems our automated fixes patch in the browser on the Enterprise plan. They guess a name from the icon’s class name or a title attribute, and when there’s nothing to go on, the button is just called “Button”. A name you write yourself is always better.

Complex images: short alt, long description nearby

Charts, diagrams, floor plans and busy screenshots cannot be summed up in 125 characters. Do not try. Use the alt for the headline and put the detail in the page:

• Alt: “Bar chart of monthly widget opens, January to June.”
• Below the chart: the actual numbers in a sentence or a small table.

Everyone benefits from this, not only screen reader users. The numbers become searchable and copyable, and the chart still does its job for people who like charts.

For screenshots, say what the screenshot demonstrates, not what is in every pixel: “Audit results page listing three contrast issues on the checkout, each with its WCAG criterion.” That is enough for someone following a tutorial.

Text inside images

If an image contains text, the alt text must contain that text. A banner that reads “Free shipping on orders over $50” needs exactly that as its alt. Otherwise the offer does not exist for part of your audience.

Better still, do not put important text in images. Real text scales, translates, reflows on a phone and can be read by everyone. WCAG covers this under 1.4.5 Images of Text, and the easiest way to pass it is to use text.

A five-minute check before you publish

• Every img has an alt attribute. Empty is fine; missing is not.
• No alt starts with “image of”, “picture of” or “photo of”.
• Decorative images have alt="".
• Linked images describe the destination.
• Product alts mention color, material and shape, not keywords.
• Nothing important is said only inside an image.
• Read the page with images turned off, or with a screen reader, and see if it still makes sense.

Where the tooling fits

Missing alt text fails WCAG success criterion 1.1.1, Non-text Content, and every automated checker looks for it. Accessora’s audits scan the pages you add and list each image without alt text, with the WCAG criterion it fails and the element it was found on. On Growth and Enterprise, AI alt text fills in a generated description for images that have none while you work through the list, so visitors don’t hear file names in the meantime. It treats an empty alt="" as missing too, so check the images you meant to mark decorative.

A generated description is a stopgap. The alt text that really helps is written by someone who knows why the image is on the page. If you run a WordPress site, the media library has an alt field on every upload. Shopify has one on every product image. Fill them in as you go, and the audit list gets shorter on its own.

For the wider picture, read WCAG 2.2 in plain English for small sites for the rest of the standard, and Widgets, overlays and real fixes for an honest look at what a widget can and cannot do about images.