Why does the suggested alt change so much when I switch the role?

Because alt text is not one-size-fits-all — the same image needs different alt depending on the job it does. A photo used as decoration takes alt=""; the same photo used as a homepage logo link takes “Home”; as a standalone hero it takes a description of what it shows. The role is the single most important decision, so this tool makes you choose it first and then applies the matching recipe automatically.

How do I know which role my image is?

Start with one question: would the page lose information if the image were gone? If no, it’s decorative (alt=""). If the image is inside a link or button, it’s functional — describe the destination. If it’s a chart, graph, diagram, or map carrying data, it’s complex and needs a long description. If it’s essentially a picture of text, it’s text-in-image. If several images form one unit, it’s a group. Everything else is informative. That sequence is the W3C alt decision tree, and the About panel lays it out.

Why does a functional image describe the link instead of the picture?

When an image is the only content of a link or button, its alt becomes the accessible name of that control. A magnifier icon that submits a search should have alt="Search", not alt="Magnifying glass", because the user needs to know where the link goes, not what the icon looks like. Describing the picture would leave the control’s purpose unstated and can fail WCAG 2.4.4 Link Purpose.

Why can’t I just write a long, detailed alt for a chart?

A 200-character alt is exhausting to listen to and is often skipped. For complex images the accessible answer is a short alt that names the chart and its takeaway, with the full data provided as real text elsewhere — a visible figcaption, an aria-describedby target, or a collapsible details element. The tool generates whichever pattern you choose, so the numbers live in text that everyone (including search engines) can read.

What does the linter check, and what is WCAG 1.4.5?

The linter flags the failures people actually ship: a non-decorative image with no alt, a decorative image with a non-empty alt, redundant “image of / photo of” openers, alt text that looks like a filename (extensions, underscores, camelCase), alt over 125 characters, and comma-stuffed keyword lists. For text-in-image it also raises WCAG 1.4.5 Images of Text — text baked into an image can’t be resized, recoloured, or selected, so real CSS-styled text is preferred unless it’s a logo.

Does it look at my actual image file?

No. It doesn’t upload or analyse pixels — it composes alt text from the role and the details you describe, which keeps it private and instant. Because you know what the image conveys in its context, the result is an accurate, WCAG-aligned draft and the correct markup pattern, not a generic guess. The image type, your inputs, and the chosen output dialect are all encoded in the shareable URL.

Alt Text Suggester

Alt text isn’t one-size-fits-all — the image’s role decides the recipe. Tell the tool what job the image does (informative, decorative, functional, a complex chart, text-in-image, or one of a group) and it composes the right alt and the right markup: alt="" for decorative, the link destination for functional, a short alt plus a separate long description for charts, a verbatim transcription for text images. It reads the result back the way a screen reader would and lints it against WCAG 1.1.1 (and 1.4.5).

About this ToolHow it works, benefits & use cases

Most alt-text helpers treat every image the same — fill in a box, get a string. But alt text is not one-size-fits-all: the job an image does on the page decides the correct recipe. This tool walks the W3C alt decision tree for you. Pick the image’s role — informative (a photo or illustration that adds information), decorative (a spacer or flourish that adds none), functional (an image inside a link or button), complex (a chart, graph, diagram, or map), text-in-image (a picture of words), or one of a group — and it composes the right alt and the right markup. A decorative image resolves to alt=""; a functional image describes the link’s destination instead of the picture; a complex image gets a short alt plus a separate long description (figcaption, aria-describedby, or a collapsible <details>) because the data must live in real text; a text image is transcribed verbatim with a 1.4.5 warning. The tool reads the result back the way a screen reader would announce it, generates copy-paste HTML or JSX, and lints the alt against WCAG 1.1.1 pitfalls — empty alt on a non-decorative image, “image of” redundancy, filename-looking alt, over-125-character length, and keyword stuffing. There’s a second mode for pasting an existing alt to audit it, and the whole configuration is shareable via URL.

How to Use

1Answer the decision-tree question — what job does the image do? Pick informative, decorative, functional, complex, text-in-image, or group.
2Fill in only the fields that role needs: subject/action/context for informative, the link destination for functional, the chart name plus a long description for complex, or the verbatim words for a text image.
3Read the “Screen reader announces” preview to confirm the alt and how it’s spoken, and check the lint card for WCAG issues.
4For a complex image, choose how the long description is wired — figcaption, aria-describedby, or a <details> disclosure.
5Toggle HTML or JSX, then copy the generated <img> (or figure) markup, or share the URL with a teammate.
6Switch to “Lint existing alt” to paste an alt string, choose its role, and audit it against the same rules.

Key Benefits

Role-driven: the image’s job (informative / decorative / functional / complex / text-in-image / group) picks the recipe
Correctly produces alt="" for decorative images and keeps the attribute so AT doesn’t read the filename
Functional images describe the link/button destination, not the picture (the alt becomes the control’s name)
Complex images get a short alt plus a real-text long description via figcaption, aria-describedby, or <details>
Generates the full, correct markup pattern per role in copy-paste HTML or JSX — not just a bare string
Live screen-reader-style announcement preview so you hear what users hear
Lints against WCAG 1.1.1 (and 1.4.5 for text images): empty alt, “image of”, filenames, length, keyword stuffing
Separate lint mode to audit existing alt text, plus a shareable URL for handoff

Common Use Cases

Deciding whether a hero photo is informative or decorative using the “would the page lose information?” test
Writing the alt for a logo that links to the homepage so it announces “Home”, not “Company logo”
Pairing a short alt with a real-text long description for a quarterly-revenue bar chart
Transcribing a quote graphic verbatim — and getting the nudge to use real text instead (1.4.5)
Describing a star-rating row once and using alt="" on the rest so it isn’t announced five times
Auditing a content team’s existing alt attributes and explaining each WCAG violation

Screen reader announces

“Golden retriever puppy splashing through shallow surf on a sunny beach, graphic”

alt: Golden retriever puppy splashing through shallow surf on a sunny beachLength: 70 / 125

Informative — a concise description of what matters (subject + the salient detail). Keep it ≤125 characters and skip “image of”.

Generated markup

Informative image — HTML

<img src="…" alt="Golden retriever puppy splashing through shallow surf on a sunny beach" />

No accessibility issues found

Relevant WCAG1.1.1 Non-text Content (A)

Informative — the recipe

Write a concise description of what matters: the subject plus the one salient detail. Aim for ≤125 characters. Skip "image of".

What job does the image do?

The image adds information the surrounding text does not — a photo, illustration, or icon that the reader would miss if it were gone.

Describe the image

Subject — what/who

Action (optional)

Context / setting (optional)

Output

The alt decision tree

Good alt text starts with one question: would the page lose information if this image disappeared? If not, it’s decorative → alt="". If the image is inside a link or button, it’s functional → describe the destination, not the picture. A chart or diagram is complex → a short alt plus a long description in real text. A picture of words is text-in-image → transcribe verbatim. Otherwise it’s informative → a concise description of what matters.

Why the role matters

The same photo needs different alt as a hero image vs. a logo that links home.
A 200-character alt on a chart is unusable — the data belongs in text on the page.
A missing alt is worse than an empty one: screen readers fall back to reading the filename.

Was this tool helpful?

Share Your Experience

Help others discover this tool!

Share on

Alt Text Suggester

How to Use

Key Benefits

Common Use Cases

Screen reader announces

What job does the image do?

Describe the image

Output

The alt decision tree

Why the role matters

Was this tool helpful?

Share Your Experience

Related tools

Frequently Asked Questions - Alt Text Suggester