Alt text best practices, with examples for every kind of image

First decide: informative or decorative?

Every <img> needs an alt attribute. The only question is what goes in it. Ask one thing: if the image failed to load, would the reader miss any information?

• If yes, the image is informative. Write what it shows or what it does, in a few words.
• If no, it is decorative. Use an empty alt="". Screen readers skip it completely.

Leaving the attribute out is the worst option. Without alt, many screen readers read the file name instead, so a user hears "IMG underscore 2041 dot jpg". That is why a missing alt is a critical finding under WCAG 1.1.1 Non-text Content.

<!-- Before -->
<img src="IMG_2041.jpg">
<img src="divider-swirl.png">

<!-- After -->
<img src="IMG_2041.jpg" alt="Two nurses checking a patient's blood pressure">
<img src="divider-swirl.png" alt="">

Typical decorative images are background flourishes, spacers, divider lines, and photos that only repeat text already next to them. a11ymedic uses clues like a file name containing "divider" or "spacer", a 1 by 1 tracking pixel, or a link that already has text, and offers alt="" as a safe automatic fix in those cases.

How to write good alt text

Think of alt text as what you would say if you were reading the page to a friend over the phone.

• Be specific about what matters. "Red running shoe, side view, with a white sole" is more useful on a product page than "Shoe".
• Write for the context. The same photo of a CEO might be "Ana Souza, CEO" on a team page and "Ana Souza speaking at the 2026 product launch" in a news article.
• Keep it short. One sentence is usually enough. Screen readers cannot pause or navigate inside alt text, so long descriptions are tiring. a11ymedic flags alt text over 150 characters.
• Do not start with "image of" or "picture of". Screen readers already announce that it is an image. Removing the prefix is a safe automatic fix.
• Never use a file name or a placeholder. "hero.jpg", "image", "photo" and "untitled" are flagged because they say nothing.
• Include text that appears in the image. If a graphic says "50% off until Friday", the alt must say it too.

Images inside links and buttons

When an image is the only content of a link or button, its alt text becomes the name of that control. So it must describe the destination or action, not the picture. A magnifier icon in a search button should be "Search", not "Magnifying glass". A logo that links home should be "Acme home", not "Acme logo".

<!-- Before: the link has no name -->
<a href="/"><img src="logo.svg"></a>

<!-- After -->
<a href="/"><img src="logo.svg" alt="Acme home"></a>

<!-- Image and text in the same link: the text already names it -->
<a href="/cart"><img src="cart.svg" alt=""> Cart</a>

In the last example the visible word "Cart" names the link, so the icon gets alt="". If you gave it alt="Cart" as well, screen readers would say "Cart Cart". a11ymedic reports that repetition and fixes it automatically.

SVG icons and icon fonts

Inline SVG has no alt attribute. If the SVG is the only content of a button, give the button an aria-label and hide the SVG from assistive technology. If the SVG is a standalone meaningful graphic, give it role="img" and a name.

<!-- Icon only button -->
<button type="button" aria-label="Close">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">...</svg>
</button>

<!-- Standalone graphic -->
<svg role="img" aria-label="Rating: 4 out of 5 stars" viewBox="0 0 120 24">...</svg>

The rules involved are button-name for the empty button and role-img-alt for an element with role="img" but no name. Image buttons (<input type="image">) and image map areas follow the same idea and are checked by input-image-alt and area-alt.

Charts, diagrams and other complex images

A bar chart with twelve values cannot fit in one sentence. Use a short alt that says what the chart is and its main point, then put the full data in visible text, a table or a <figcaption>. Everyone benefits from a data table, not only screen reader users.

<figure>
  <img src="signups.png"
       alt="Bar chart: monthly signups doubled between January and June"
       aria-describedby="signups-data">
  <figcaption id="signups-data">
    Signups per month: January 1,200; February 1,450; March 1,700;
    April 1,900; May 2,150; June 2,430.
  </figcaption>
</figure>

Check and fix alt text automatically

A tool cannot tell whether a description is accurate, but it can find every image with no alt, every alt that is a file name or a placeholder, every redundant prefix, every alt that repeats the link text, and every alt that is too long. It also suggests a starting point for each missing alt, taken from a caption, a title attribute, the file name or the link destination.

# See which images fail
npx a11ymedic "src/**/*.html" --rules image-alt,image-alt-quality,role-img-alt

# Preview the safe fixes (empty alt on decorative images, prefix removal) as a diff
npx a11ymedic fix "src/**/*.html"

# Apply them
npx a11ymedic fix "src/**/*.html" --write

Only fixes that need no human decision are applied. A real description is never written for you, because only a person who knows the content can write it. After the automated pass, read your alt texts out loud without looking at the images. If you get the same information, they are good.

See the rules reference for all the image checks, or paste a snippet into the online check-up.