Crawvix

How to Write Alt Text: Examples for Every Type of Image

Crawvix Editorial Team · Published November 1, 2026 · Last updated November 1, 2026 · 10 min read

Alt text is a short written replacement for an image, placed in the alt attribute of the HTML img element. The core of how to write alt text is to describe what the image contributes to the page, as if you were reading the page aloud to someone who cannot see it. If the image carries information, say that information briefly. If it is a link or a button, say where it goes or what it does. If it is only decoration, leave the attribute empty (alt="") so assistive software skips it.

This guide shows how to write alt text for photos, logos, icons, charts, screenshots and product images, with a table of before-and-after rewrites and a method for auditing a whole site. It is written for site owners, editors and developers, and each term is explained once. Helping people who use screen readers is the main reason to write alt text. Google's image guidance also says it uses alt text, together with computer vision and the content of the page, to understand an image, so good alt text for people is usually good alt text for search too.

Before you begin

You will need:

  • Access to where alt text is stored: HTML templates, the CMS media library, product data fields or the page builder.
  • A screen reader to test with, if possible, such as NVDA (free, Windows), VoiceOver (macOS and iOS) or TalkBack (Android).

The main risk is writing text that sounds helpful but repeats information or stuffs in keywords. Review each change by listening to the page.

What alt text is and who it serves

<img src="/images/team-picnic.jpg" alt="Five colleagues eating lunch at a picnic table in a park" width="1200" height="800">
Who or what How alt text helps
Screen reader users The screen reader announces the text in place of the image.
People whose images fail to load Browsers may show the alt text where the image should be.
Search engines Alt text is one signal, alongside the page content, that explains what an image shows.
Link and button users Alt text on a linked image becomes the name of the link, which matters for keyboard and voice navigation.

Under the Web Content Accessibility Guidelines (WCAG), a text alternative for non-text content is a Level A requirement.

How to write alt text for each type of image

The W3C Web Accessibility Initiative (WAI) publishes an alt decision tree. It starts with one question: why is this image here? The answer decides what, if anything, to write.

Image type What it is What to do
Informative A photo, illustration or diagram that adds meaning Write a short description of the meaning.
Decorative Styling with no information Use an empty alt="".
Functional An image inside a link or button Describe the action or destination, not the picture.
Image of text Words drawn as an image Repeat the words.
Complex A chart, graph, map or infographic Short alt, with a longer description in the page text.

Informative images

Say what matters about the image on this page. A photo on a dog-training page might get alt="Golden retriever leaping to catch a red frisbee".

Decorative images

If removing the image changes nothing for someone who cannot see it, use an empty attribute:

<img src="/images/divider-swirl.svg" alt="" width="600" height="40">

An empty alt is a deliberate statement: nothing to read here. A missing alt attribute is different. It is generally invalid HTML for an img element and may lead a screen reader to announce the file name or address instead. Always include the attribute, and leave it empty only when that is the right answer. Do not put a space inside the quotes.

When an image is the only content of a link or button, the alt text should name the destination or action:

<a href="/"><img src="/images/logo.svg" alt="Example Shop home page" width="160" height="40"></a>

<button type="submit"><img src="/icons/search.svg" alt="Search" width="24" height="24"></button>

If a link has visible text next to the icon, the icon is usually decorative.

Images of text

For a banner reading "Free shipping over $50", the alt text should hold the same words. Better still, use real HTML text styled with CSS.

Complex images: charts, graphs and maps

Give a short alt that names the image and its main point, then provide the detail nearby as ordinary text, such as a data table:

<figure>
  <img src="/images/signups-2026.png"
       alt="Bar chart of monthly newsletter signups, rising from January to June. Full figures are in the table below."
       width="900" height="500">
  <figcaption>Monthly newsletter signups, January to June.</figcaption>
</figure>

Put the long description where everyone can read it, since support for hidden description techniques varies.

Groups, logos, products and backgrounds

An unlinked logo can carry the organization's name. Product images should name the product and the visible variation, such as colour or angle, and each photo of the same product should differ: front, side, in use.

CSS background images have no alt text. That is fine for decoration. If a background image carries meaning, make it an img element, because Google states that it does not index CSS images. Hide icon fonts and decorative inline SVGs from assistive tools with aria-hidden="true". For a meaningful inline SVG, role="img" with an accessible name is commonly used; check current WAI guidance.

How long should alt text be?

HTML sets no character limit for alt. You may see "125 characters" quoted as a rule, but that comes from habits of particular tools, not from a standard. Use this instead:

  • A simple photo or icon often needs only a few words.
  • A chart needs a short alt plus a longer description in the page.
  • If you want a paragraph in the attribute, move that text onto the page.

What not to write

Avoid Why Instead
"Image of..." or "Photo of..." Screen readers already announce an image. Start with the subject. Say "photo" only when the medium matters, such as a painting.
Keyword lists Hard to hear, and Google's guidance warns against keyword stuffing in alt. Describe the image honestly.
File names such as IMG_4821.jpg Says nothing about the picture. Describe what it shows.
The same text as the caption Users hear it twice. Add what the caption lacks, or use alt="".

The same image, different alt text

The right text depends on the page. Here is one bridge photo in two places:

<!-- Travel blog about a weekend in San Francisco -->
<img src="/img/bridge.jpg" alt="Golden Gate Bridge glowing orange at dusk, seen from the north shore">

<!-- Engineering article about cable design -->
<img src="/img/bridge.jpg" alt="Main suspension cables and vertical suspender ropes of a long-span bridge">

Ask "what does this image do on this page?" each time. Many CMS tools store one alt per file, so check whether yours allows an override per page.

Fourteen before-and-after examples

These are illustrations, not data from a real site.

# Image and context Weak alt text Better alt text
1 Dog photo in a training article dog Golden retriever leaping to catch a red frisbee in a park
2 Running shoe product photo BEST CHEAP RUNNING SHOES SALE Trailrunner 2 running shoe in blue, side view
3 Logo linking to the home page logo Example Shop home page
4 Search icon in a button magnifying glass Search
5 Decorative divider line decorative swirl Empty: alt=""
6 Banner image of text banner Free shipping on orders over $50
7 Bar chart of signups chart Bar chart of monthly signups, rising from January to June. Full figures in the table below.
8 Map of a shop location map Map showing the shop on the corner of Main Street and 2nd Avenue, two blocks north of the station
9 Software screenshot in a tutorial screenshot Settings page with the Notifications tab selected and the Email toggle switched on
10 Staff headshot on a team page photo of Priya Priya Shah, Head of Support
11 Photo captioned "A volunteer planting seedlings" A volunteer planting seedlings Gloved hands pressing a seedling into dark soil
12 Recipe photo food Bowl of tomato soup topped with basil and a swirl of cream
13 Social media icon link icon Example Shop on Facebook
14 Avatar beside a commenter's name avatar Empty: alt="", because the name is already beside it

Step-by-step instructions

Step 1: List the images on a page

In browser developer tools, run this in the console to list images with no alt attribute:

[...document.images]
  .filter(img => !img.hasAttribute('alt'))
  .map(img => img.currentSrc || img.src)

Run it again with img.getAttribute('alt') === '' to list images marked decorative. If your main product photos appear there, something is wrong.

What success looks like: you have two lists, images with no alt and images with an empty one.

Step 2: Decide each image's purpose and write the text

Ask the decision-tree question for each image and record the type in a spreadsheet column.

Write for the page's context. Read it aloud, and shorten it if it repeats the sentence before it. Automatic captioning tools can draft alt text from an image, which may save time on a large library. A person must review every draft, because such tools can misread a scene, miss what matters in your context or describe things that are not there.

What success looks like: each image has a type and, unless decorative, text that fits its role.

Step 3: Fix it at the source

Change the template or data, not just the rendered HTML: the CMS alt field, the product data field your theme uses, or the image component in your framework. Make alt a required property of the component so new images cannot be added without a decision.

What success looks like: the problem does not return when someone adds a new page.

Step 4: Test with a screen reader

Move through the page image by image. Check that every linked image has a name, and listen for repeated text, file names and the word "image".

What success looks like: a person who cannot see the page can follow it.

Step 5: Repeat at scale

Work in priority order: the most visited pages, then shared templates such as headers and product cards, then the long tail. Re-run the audit after releases.

What success looks like: the count of missing alt text falls and stays low.

Using Crawvix to find images that need attention

Crawvix's Image Doctor lists the images written into the HTML of the pages of a full scan of a verified website (up to 2,000), checks up to 200 of them for status, type and file size, and reports missing or generic alt text, broken images, large files, missing width and height, a lazily loaded first image, older formats and generic file names. Each finding comes with evidence and what to do, and there is a CSV export. It only reads a website and never changes it. A tool can show that alt text is missing or generic, but only a person can judge whether the text is accurate. Try it at /image-doctor.

Final verification checklist

  • Every img element has an alt attribute, even if empty.
  • Decorative images use alt="" with no spaces.
  • Informative images say what they add to the page.
  • Linked images and icon buttons name the destination or action.
  • Images of text repeat their words.
  • Charts and maps have a short alt and a fuller description in the page.
  • No alt text is a keyword list, a file name or a repeat of the caption.
  • Any machine-written draft was reviewed by a person.

Common mistakes to avoid

  • Leaving the attribute out. A missing alt is a different signal from an empty one.
  • Stuffing keywords. Screen reader users hear every word.
  • Adding "image of". The role is already announced.
  • Describing the picture on a linked image instead of the destination. The link needs a name.

Frequently asked questions

What is alt text in simple terms?

Alt text is the written description in an image's alt attribute. Screen readers read it aloud, browsers may show it if the image does not load, and search engines use it as context. It should say what the image means on its page.

How long should alt text be?

There is no fixed limit in HTML. A few words suit a simple image and a sentence suits a complex one. Put any extra detail in the visible page and keep the alt as a summary.

Should every image have alt text?

Every img element should have the alt attribute. Informative images need descriptive text, and decorative ones need an empty value.

Does alt text help SEO?

Google says it uses alt text, along with other signals, to understand an image, and that it is useful as anchor text when an image is a link. No ranking effect is promised, so write for people first.

What does an empty alt attribute mean?

It tells assistive software the image is decorative or redundant, so it should be ignored. It is different from having no alt attribute, which is generally invalid and may cause a screen reader to read out the file name.

Can a tool write my alt text for me?

Automatic tools can draft alt text, and drafts can help with a large backlog. A person must read and correct each one, because the tool does not know your page's purpose.

Official references

Next step: Run Image Doctor to list missing and generic alt text on a verified website, or scan the whole website for wider technical checks. This guide provides technical information, not a guarantee of rankings, traffic or index inclusion.