How to Write Alt Text: Image Description Rules + Examples

Originally published at AccessGuard.

Alt text is one of the oldest accessibility features on the web

The alt attribute has been part of HTML since 1995. It exists for a simple reason: not everyone can see your images. Screen reader users, people with slow connections who disable image loading, and search engine crawlers all rely on alt text to understand what an image conveys.

Yet despite being one of the most well-known accessibility requirements, alt text remains one of the most frequently failed. The WebAIM Million study consistently finds that over a third of all images on the web are missing alt text entirely. And among those that do have it, many are written poorly - either too vague to be useful or so verbose they become a burden.

Writing good alt text is a skill. This guide covers the principles, patterns, and common mistakes so you can get it right every time.

The three types of images

Before you write alt text, you need to determine what role the image plays on the page. Every image falls into one of three categories, and each requires a different approach.

Informational images

These images convey content that isn't available in the surrounding text. They add meaning to the page, and without them, a user would miss something important.

Examples include product photos, team headshots, infographics, screenshots demonstrating a feature, and editorial photos that support an article's narrative.

For informational images, write alt text that conveys the purpose and content of the image:

<img src="dashboard.png" alt="AccessGuard scan results showing 12 errors, 8 warnings, and 23 notices across 5 pages">

Notice this describes what the image communicates, not just what it looks like. "Screenshot of a dashboard" would be technically accurate but useless - it doesn't tell the user what they'd learn from seeing the image.

Functional images

These images serve as interactive controls - icons inside buttons, linked logos, image-based navigation. Their purpose is to trigger an action, not to convey visual content.

For functional images, the alt text should describe the action or destination, not the image's appearance:

<a href="/"><img src="logo.svg" alt="AccessGuard home page"></a>

<button><img src="close.svg" alt="Close dialog"></button>

Writing "company logo" or "X icon" describes what the image looks like, but doesn't tell the user what will happen when they activate it. Always describe the function.

Decorative images

These images exist purely for visual appeal - background textures, decorative dividers, abstract patterns, or stock photos that don't add information beyond what's already in the text.

Decorative images should have an empty alt attribute so screen readers skip them entirely:

<img src="decorative-wave.svg" alt="">

This is not the same as omitting the alt attribute. A missing alt attribute causes screen readers to announce the file name, which is worse than no description at all. An empty alt="" explicitly tells assistive technology to ignore the image.

If you're using CSS background images for decoration, they're already invisible to screen readers - no alt text needed.

Writing effective descriptions

Once you've determined an image needs descriptive alt text, follow these guidelines to write it well:

Be concise but complete

Good alt text is typically one to two sentences. It should convey the essential information without unnecessary detail. Think of it as a brief caption, not a paragraph.

• Too short: alt="Graph" - tells the user nothing about what the graph shows
• Too long: alt="A bar graph with a blue background and gray grid lines showing monthly revenue data from January through December 2024 with values labeled on the y-axis in increments of $10,000..." - overwhelming and includes visual details that don't matter
• Just right: alt="Monthly revenue chart showing steady growth from $40,000 in January to $85,000 in December 2024" - communicates the key takeaway

Focus on purpose, not appearance

Ask yourself: "If I couldn't see this image, what would I need to know?" The answer is rarely about visual details like colors and layout. It's about the information or meaning the image adds to the page.

For a team photo on an about page, alt="Five team members smiling in an office" is less useful than alt="The AccessGuard founding team at our Portland headquarters". The second version tells the user what the photo means in context.

Don't start with "image of" or "photo of"

Screen readers already announce that an element is an image before reading the alt text. Writing alt="Image of a sunset" results in the user hearing "Image: Image of a sunset" - which is redundant. Just write alt="Sunset over the Pacific Ocean from the Oregon coast".

The exception is when the medium itself is relevant: alt="Oil painting of sunflowers by Vincent van Gogh" where the fact that it's a painting matters.

Complex images: charts, infographics, and diagrams

Some images contain more information than a brief alt text can reasonably convey. Charts, data visualizations, infographics, and technical diagrams often fall into this category.

For complex images, use a two-part approach:

1. A brief alt text that summarizes the key takeaway: alt="Bar chart comparing accessibility scores across 5 industries, with healthcare scoring highest"
2. A detailed text alternative elsewhere on the page - either in the surrounding content, a data table, or a linked description. You can connect them using aria-describedby:

<img src="chart.png" alt="Industry accessibility scores comparison" aria-describedby="chart-data">
<table id="chart-data">...</table>

This gives screen reader users the summary first, with the option to explore the full data. It also benefits sighted users who may struggle to read small text within chart images.

Common alt text mistakes

Even well-intentioned alt text can miss the mark. Here are the most common mistakes to avoid:

• Using the file name as alt text. alt="IMG_4829.jpg" or alt="hero-banner-final-v2" conveys nothing meaningful. Always write a human-readable description.
• Stuffing keywords for SEO. alt="best web accessibility tool scanner WCAG compliance checker free" is a terrible experience for screen reader users and search engines are smart enough to recognize keyword stuffing. Write for humans first.
• Being too generic. alt="Person using computer" is technically descriptive but doesn't tell the user why this specific image is on this specific page. Add context.
• Describing decorative images. If an image doesn't add information, give it alt="". Forcing screen reader users to listen to descriptions of abstract patterns and stock photography wastes their time.
• Forgetting alt on linked images. When an image is the only content inside a link, the alt text becomes the link text. If it's empty, screen readers may announce the URL or "link image" with no indication of where it goes.

How to check whether an image already has alt text

Everything above is about writing alt text. Auditing a site somebody else built is the other half of the job: the images are already there, and you need to know which ones are described, which are silently empty and which are missing the attribute altogether.

Inspect the element

Right click the image, choose Inspect, and read the <img> tag in DevTools. That is the whole technique, and it is the only one that distinguishes the three states reliably.

<!-- Described: a screen reader reads the text -->
<img src="chart.png" alt="Revenue fell 12% between March and June">

<!-- Deliberately silent: the screen reader skips it entirely -->
<img src="corner-flourish.svg" alt="">

<!-- Broken: no alt attribute at all -->
<img src="team-photo.jpg">

The difference between the second and the third matters more than it looks.

• alt="" is a decision. It says the image carries no information, so assistive technology should ignore it. On a decorative flourish that is correct and is what you want to see.
• No alt attribute is an absence. Screen readers fall back to announcing something, often the file name, so a person hears "team dash photo dash final dash v2 dot jpg". On a linked image with no alt, they may hear the whole URL and no indication of where the link goes.

So a page full of alt="" can be perfect, and a page full of missing attributes never is. A report that lumps them together is wrong, and clients notice.

Why hovering is not a test

The tooltip that appears when you hover an image comes from the title attribute, not from alt. They are different attributes with different audiences: title is a mouse hover affordance that most screen readers do not announce by default and that touch users never see at all. An image can show a helpful tooltip and still be completely silent to a screen reader, and an image with excellent alt text usually shows no tooltip at all. If your check is "hover and see if something appears", you will pass broken images and fail good ones.

Checking a whole page at once

Inspecting one image is fine. Inspecting four hundred on a client site is not. Paste this into the console to list every image and its state:

console.table([...document.images].map(img => ({
  src: img.currentSrc.split('/').pop(),
  state: !img.hasAttribute('alt') ? 'MISSING attribute'
        : img.alt.trim() === ''   ? 'empty (decorative)'
        : img.alt,
  linked: !!img.closest('a')
})));

The linked column is the one to sort by. A linked image with no alt or an empty alt is the worst case on the page, because the link itself then has no accessible name, and that is a Level A failure rather than a judgement call.

What a scanner catches, and what it does not

An automated check is very good at exactly one part of this: finding images with no alt attribute, empty alt on a linked image, and alt text that is obviously junk, such as a file name or the word "image". Our alt text checker runs that across every page you add, and a free accessibility scan gives you the count on a client page in a couple of minutes.

What it cannot do is judge whether the description is right. alt="chart" on a revenue chart passes every automated test ever written and tells a person nothing. Deciding that an image is decorative, and that alt="" is therefore correct rather than lazy, is also a human call: the scanner cannot see that the photo next to the quote is the person being quoted. So the count comes from the tool and the judgement comes from you, which is the honest version to put in a proposal. Automated checks find many real problems, but no scan can confirm that a page conforms to WCAG.

How AccessGuard helps with alt text

Manually checking every image on a growing website is tedious and easy to overlook. AccessGuard's alt text checker identifies every image on your pages that's missing alt text or has potentially problematic alt text (like file names or single-word descriptions).

For images that need alt text, AccessGuard also offers AI-powered alt text generation - providing a starting point that you can review and refine for your specific context. This is especially useful for sites with hundreds or thousands of images where writing alt text from scratch would be impractical.

The combination of automated detection and AI-assisted writing means your team can address alt text gaps efficiently without sacrificing quality.