How to Use the Alt Attribute in an HTML Image Tag

The alt attribute provides a text alternative for an HTML <img>. Put it in the opening tag and write the information or action the image contributes in its surrounding context.

<img src="photo.jpg" alt="A red bicycle leaning against a brick wall">

The correct value depends on the image’s purpose. Informative images need a concise description of their meaning, decorative images need an exactly empty value (alt=""), and functional images need the action or destination they provide.

1. What the alt attribute does

Browsers and assistive technologies use alt when an image cannot be seen or loaded. It can also appear when a file fails to download. The goal is not to inventory every visible detail; it is to preserve the image’s relevant meaning for this page.

WCAG Technique H37 states: “When using the img element, specify a short text alternative with the alt attribute.” Read the official H37 technique for the normative guidance.

2. Choose the value by image purpose

Informative images

An informative image adds content that readers need. Describe that content briefly and put the most important information first.

<img src="sales-chart.png" alt="Sales increased from January through June, then leveled off in July">

If words inside the image matter, include those words or provide the complete information in nearby text. A longer chart explanation belongs in the surrounding article; the alt value can remain a concise summary.

For a diagram, describe its key message rather than listing shapes and colors:

<img src="deployment-flow.svg" alt="Code moves from commit to tests, then to production">

See the W3C informative images guidance.

Decorative images

A decorative image adds styling or atmosphere but no information needed to understand the page. Keep the attribute and make its value exactly empty:

<img src="section-border.png" alt="">

An empty value tells a screen reader to skip the image. Omitting alt is different: assistive technology may announce the filename or treat the image as an unknown object. Do not use a space inside the quotes; use alt="".

W3C explains this distinction in its decorative images tutorial.

Functional images

When an image is a link or button, describe what activating it does or where it goes. Describe the action, not the visual object.

<a href="/print">
  <img src="print.svg" alt="Print this page">
</a>

<a href="/">
  <img src="brand-mark.svg" alt="Home">
</a>

If visible link text already states the same destination, make the adjacent image redundant with alt="":

<a href="/account">
  <img src="avatar.svg" alt="">
  Account settings
</a>

Consult the W3C functional images guidance.

3. A practical decision process

1. Ask whether the image conveys information unique to this page.
2. If it does, write a short alternative that conveys that information.
3. If it is a link or button, describe the destination or action.
4. If nearby text already communicates the image’s purpose, use alt="" to avoid repetition.
5. If the image is purely decorative, use alt="".
6. If a short alternative cannot carry all the detail, put the detail in surrounding text or a suitable long-description pattern.

The W3C alt decision tree walks through these questions.

4. How to write concise, useful alt text

• Start with the information a reader needs first.
• Use normal sentence punctuation when it helps the text read naturally aloud.
• Usually omit filler such as “image,” “picture,” or “icon”; screen readers already identify images.
• Name people, places, objects, or states only when they matter to the content.
• Do not add opinions that the image does not support.
• Do not repeat a caption or adjacent paragraph word for word unless that repetition is necessary.
• Keep decorative alternatives empty rather than writing “decorative image.”

For example, an article about bicycle safety benefits from alt="Cyclist wearing a helmet in a marked bike lane". An unrelated stock photo beside the same paragraph may need alt="".

5. Common patterns and edge cases

Images with captions

A caption can provide context that is longer than the alternative. Let alt identify the image’s essential content without duplicating the entire caption.

<figure>
  <img src="server-room.jpg" alt="Rows of servers with blue status lights">
  <figcaption>The company moved its production workloads to a new facility in June.</figcaption>
</figure>

Logos

A standalone logo that links home commonly uses the destination as its alternative, such as alt="Home". A logo next to a visible company name can use alt="" to avoid saying the name twice.

Charts, diagrams, and maps

Summarize the conclusion or purpose in alt, then provide data or a detailed explanation in nearby HTML. Do not force a multi-paragraph data table into one attribute.

Images containing text

If the text is essential and is not repeated elsewhere, include it in the alternative. Better still, provide the text as real HTML when possible so it can be selected, translated, and resized.

CSS backgrounds

Background images do not use alt. If a background conveys information, expose that information in HTML text or an actual <img>.

Responsive images

Use one meaningful alternative while changing files with srcset or <picture>:

<picture>
  <source media="(min-width: 800px)" srcset="hero-wide.jpg">
  <img src="hero-small.jpg" alt="Aerial view of the coastal trail at sunrise">
</picture>

Broken or missing files

An alternative does not repair a broken URL, but it lets the user understand what was intended. Also verify the src, deployment path, permissions, and server response.

6. Mistakes to avoid

Mistake	Why it fails	Better approach
Omitting alt	Assistive technology may announce a filename or expose an unlabeled image.	Choose meaningful text or alt="".
Writing “image of…” everywhere	Adds repeated, low-value words.	Start with the useful information unless the image type itself matters.
Describing a functional icon as an object	“Printer” does not tell the user what activation does.	Write “Print this page.”
Repeating adjacent text	Creates needless verbosity.	Use an empty alternative for redundant images.
Using keyword lists	Produces unnatural, inaccessible output.	Write one clear phrase for the page context.
Putting long data in the attribute	Hard to navigate and maintain.	Summarize, then provide detail in HTML.

7. Testing checklist

• Inspect every content image and confirm it has an alt attribute.
• Check that informative alternatives convey the same essential point as the image.
• Check that decorative images use exactly alt="".
• Activate image links and confirm the alternative states the destination or action.
• Turn images off or test a failed request to see whether the text still makes sense.
• Use a screen reader or accessibility checker, then review the result manually; automated tools cannot judge context reliably.
• Verify that important text is real HTML when possible, rather than text baked into a bitmap.

8. Or skip the browser setup

If you are generating screenshots to review image markup, you can capture a page with ScreenshotNeo through one GET request. It accepts the cookie or consent banner as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and whether the shot was billed.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/image-demo -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/image-demo"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com/image-demo' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Options include full-page or element capture, custom CSS and JavaScript, device and viewport settings, waiting rules, request blocking, headers and cookies, caching, signed links, asynchronous jobs, bulk capture, and PDF output.

There is a free plan with 1,000 screenshots a month and no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. Troubleshooting

“The screen reader says the filename”

Cause: the alt attribute is missing. Fix: add a meaningful alternative or alt="" when the image is decorative.

“The same sentence is announced twice”

Cause: an image and nearby text duplicate one another. Fix: make the redundant image’s alternative empty.

“The icon’s purpose is unclear”

Cause: the value names the object rather than the operation. Fix: describe the action or destination, such as “Download report.”

“The alternative is huge”

Cause: detailed data was forced into one attribute. Fix: summarize in alt and move the complete explanation or table into surrounding HTML.

“The image is decorative but still announced”

Cause: the attribute is omitted or contains a space. Fix: use exactly alt="".

10. FAQ

Is alt text required on every img?

Every <img> should have an alt attribute. The value can be meaningful text or empty when the image is decorative or redundant.

Can I leave alt blank for an informative photo?

Only if the information is fully available in nearby text and the image adds no unique meaning. Otherwise, write a concise alternative.

Should alt text include keywords for SEO?

Write for the image’s purpose and the reader. Relevant, natural wording is appropriate; keyword lists are not.

How long should alt text be?

As short as the purpose allows. If the image needs extensive explanation, put that explanation in surrounding content rather than creating an unwieldy attribute.

What is the difference between missing alt and empty alt?

Missing alt leaves the image’s purpose unspecified. Empty alt="" explicitly marks it as decorative or redundant so assistive technology can skip it.

Where can I read the full guidance?

Start with the W3C WAI Images Tutorial, its tips and tricks, and the purpose-based examples linked above.