Skip to main content
Accessibility Field Guide

Alt Text Basics

Write text alternatives that explain the purpose of an image in context, not every pixel in the picture.

A notebook with wireframe sketches, a pen, and a smartphone on a wooden desk.
Photo: Notebook Beside the Iphone on Table via Pexels — https://www.pexels.com/photo/notebook-beside-the-iphone-on-table-196644/
View full screen Download image

Alt text is not a caption. It is not a file name. It is not a place to describe every visible detail.

Alt text is the text alternative that helps someone understand what an image contributes when they cannot see it, cannot load it, or are using a tool that exposes the page non-visually.

The right alt text depends on the image's purpose in that exact place.

The same photo might need a useful description in one article, be decorative in a layout, and need a different description in a step-by-step guide.

The common project moment

A team adds images to a page, product flow, document, dashboard, or article.

The page looks more complete. There is a hero image, a few icons, maybe a chart, a screenshot, a logo, or an illustration that makes the content feel friendlier.

Then the image starts carrying meaning:

  • an icon tells the user whether something is approved, overdue, or unavailable
  • a screenshot shows where to click
  • a chart explains a trend
  • a diagram shows a process
  • a product photo helps someone identify the right item
  • a decorative image is announced with a meaningless file name
  • the same image gets copied into several places with the same generic alt text

That is where alt text becomes more than a publishing checklist.

The review question is not only, "Does the image have alt text?"

It is:

What would someone miss if this image were not available?

Use this when

Use this page when a screen, document, article, or workflow includes:

  • photos
  • icons
  • illustrations
  • diagrams
  • charts or graphs
  • screenshots
  • logos
  • images used as links or buttons
  • decorative images in cards, headers, or page sections

This applies to web pages, PDFs, slides, knowledge articles, emails, dashboards, and product screens.

Start with the image's job

Before writing alt text, decide what the image is doing.

Ask:

  • Is this image decorative?
  • Does it repeat nearby text?
  • Does it explain something not written elsewhere?
  • Does it identify a person, place, object, product, or document?
  • Does it act as a control, link, or button?
  • Does it show data, a process, or a state?

The answer changes the alt text.

A useful description is not always longer. Sometimes the best alternative is an empty alt="" because the image adds no meaning beyond decoration.

Decorative images should stay quiet

If an image is purely decorative, it should usually be ignored by assistive technology.

That means using empty alt text:

<img src="divider-flourish.png" alt="">

A decorative image does not need to announce itself as decorative image, blue swirl, or header graphic.

Those words add noise without helping the user complete the task.

This often applies to background textures, ornamental separators, stock photos that do not add information, and repeated visual flourishes.

Informative images need the useful meaning

If an image adds information, the alt text should explain the useful meaning in context.

For example, if a page shows a photo of a damaged bridge as part of an inspection report, bridge may be too vague.

A better description might be:

  • Cracked concrete on the underside of the bridge deck.
  • Temporary lane closure signs on the westbound bridge approach.
  • Rust visible on the bridge support beam near the waterline.

The right version depends on what the surrounding content is trying to communicate.

Alt text should be specific enough to preserve the point of the image, but not so detailed that it distracts from the page.

Images that are controls need action names

If an image is inside a link or button, the text alternative should describe the action or destination, not just the picture.

Less helpful:

<a href="/print"><img src="printer.svg" alt="printer"></a>

More helpful:

<a href="/print"><img src="printer.svg" alt="Print application"></a>

If the button already has visible text next to the icon, the icon may be decorative:

<button><img src="trash.svg" alt=""> Delete document</button>

The user needs the control's name, not a second announcement of the icon.

Do not use file names as alt text

File names usually do not help users.

Examples like these are noise:

  • IMG_4821.jpg
  • hero-image-final-v3
  • icon-check-green
  • screenshot_2026_07_17

They may tell the team something about the asset pipeline, but they do not tell the user what the image means.

If the image needs alt text, write it for the reader. If it does not need alt text, make it quiet.

Keep captions and alt text separate

A caption is visible text near an image. Alt text is the text alternative exposed when the image itself needs a text replacement.

They can support each other, but they do not always need to say the same thing.

A caption might credit the source or explain why the image is included. Alt text should cover what the user needs from the image if they cannot see it.

For example, a Field Guide feature image might have a caption like:

Photo: Document on Top of Stationery via Pexels — source URL

That caption preserves attribution. It is not a useful replacement for the image itself.

The alt text should describe the photo literally enough for the page context.

Charts and diagrams need more than a short label

Charts, graphs, diagrams, and process images often need more than short alt text.

Short alt text can identify the image:

  • Bar chart comparing monthly application volume.
  • Diagram showing the intake-to-review workflow.

But the actual insight usually needs to be in nearby text, a data table, a summary, or a longer description.

If the chart is important, the page should not rely on the image alone to communicate the takeaway.

Ask:

  • What is the main trend, comparison, or exception?
  • Is the data available in text or a table?
  • Can the reader understand the conclusion without seeing the graphic?
  • Does the image need a longer description or supporting explanation?

Screenshots need context

Screenshots can be tricky.

A screenshot may show a setting, error state, workflow step, or visual example. A generic alt text like screenshot is usually not enough.

Better alt text names the purpose:

  • Settings screen with email notifications turned off.
  • Error summary at the top of a form with links to three fields.
  • Search results page showing the filter panel expanded.

If the screenshot is teaching someone what to do, the surrounding instructions should explain the steps in text too.

Do not make the screenshot the only source of the instruction.

Questions teams can ask

Product or business owner

  • What information is this image supposed to add?
  • Would the user lose meaning if the image did not load?
  • Is the image decorative, informative, instructional, or a control?
  • Is the important takeaway already written in text nearby?

Designer

  • Is the image carrying meaning through icons, color, position, or visual grouping?
  • Does the design rely on screenshots, diagrams, or charts to explain the task?
  • Can decorative images be hidden from assistive technology?
  • Are icon-only controls named by their action, not by the icon shape?

Developer

  • Does every meaningful img have appropriate alt text?
  • Are decorative images marked with empty alt="" or implemented in a way that stays quiet?
  • Do image links and icon buttons expose useful accessible names?
  • Are SVGs, background images, and generated icons handled intentionally?

Content owner or QA reviewer

  • Does the alt text match the image's purpose on this page?
  • Is any alt text just a file name, vague label, or repeated boilerplate?
  • Does the page explain important charts, diagrams, and screenshots in text?
  • Can someone understand the page if the images are unavailable?

Common trail hazards

Every image gets the same generic alt text

Repeated alt text like image, graphic, or photo usually does not help. It may technically fill the field, but it does not preserve meaning.

Decorative images are announced

A decorative divider, stock image, or background flourish can become clutter if it is announced to screen reader users.

Icons describe the shape instead of the action

An icon button should usually be named for what it does: Search, Delete document, Open menu, or Download PDF, not only magnifying glass, trash can, hamburger, or arrow.

Charts rely only on the picture

A chart with alt text like chart does not communicate the data. Important trends and conclusions need text support.

Screenshots replace instructions

If the page says click the button shown below and only the screenshot identifies the button, some users will not have the instruction they need.

Alt text tries to do too much

Alt text should not become a long essay when the page needs a visible explanation, data table, or long description. Put complex meaning where everyone can use it.

Small habit to build

Before accepting the alt text, cover the image and read the surrounding text plus the alt text.

If the page still makes sense, the alternative is probably doing its job.

If the page loses a key instruction, comparison, warning, or action, the image is carrying meaning that needs a better text alternative or nearby explanation.

WCAG trail markers

  • 1.1.1 Non-text Content — meaningful images need text alternatives, while decorative images can be ignored.
  • 1.3.1 Info and Relationships — images that communicate structure, data, or relationships need that meaning available in text or programmatic structure.
  • 1.4.1 Use of Color — images, icons, and charts cannot rely on color as the only way to communicate meaning.
  • 4.1.2 Name, Role, Value — image buttons, icon buttons, and linked images need useful accessible names.

What to do next