How to write alt text

What is alt text and why does it matter?

Alt text is the value of the alt attribute on an <img> element. A screen reader announces it in place of the image, and browsers display it if the image fails to load. It is the mechanism WCAG success criterion 1.1.1 exists to require.

Missing alt text is one of the most common failures on the web. WebAIM’s 2026 Million report found missing image alternatives among the top failures across the million most-visited home pages, year after year. It is also one of the cheapest to fix, which is an uncomfortable combination.

The reason it stays broken is not difficulty. It is that the person adding the image usually cannot tell anything is wrong, because they can see it.

What should alt text actually say?

Describe what the image communicates in this context, not what it depicts. That single reframing resolves most of the cases people get stuck on.

A photograph of a woman at a laptop is not usefully described as “woman at laptop”. What does it communicate here?

• On an article about remote work, it communicates nothing. It is decoration. alt="".
• In a product tour, it communicates a step: alt="The dashboard showing three open issues grouped by component".
• On a team page, it identifies a person: alt="Priya Raman, engineering lead".

Same file, three different correct answers, and one of them is silence. This is why alt text resists automation: the right words depend on the job the image is doing on that page.

A few patterns worth having ready:

• Charts and graphs. Give the finding, not the format. alt="Bar chart showing accessibility findings falling from 240 to 31 over six months" beats alt="bar chart". If the chart carries more data than a sentence can hold, put a table or summary in the page and keep the alt short.
• Images inside links. The alt text becomes the link’s accessible name, so it must describe the destination rather than the picture. A logo linking home takes alt="RedFlag home", not alt="RedFlag logo".
• Icon buttons. If the icon is the only content of a button, the button needs a name. Usually that is aria-label on the button rather than alt on an inline SVG. The accessible-name rule covers the variants.
• Text in images. Repeat the text. A banner reading “30% off until Friday” takes exactly that as its alt.
• Screenshots. Describe what the reader is meant to notice, not every pixel. The point of a screenshot is usually one thing.

When should alt text be empty?

When the image adds no information the surrounding content does not already carry. Then write alt="", with nothing between the quotes.

This is the part people get wrong in both directions. An empty alt attribute is an instruction: it tells assistive technology this image is decorative and should be skipped. Omitting the attribute entirely is not the same thing. Faced with a missing attribute, some screen readers fall back to reading the filename, which is how users end up listening to IMG_20260813_final_v2_approved.jpg.

So: decorative images get alt="". Every image gets the attribute. The empty string is a decision you made, and it reads as one.

The other common error is redundancy. If an icon sits immediately beside a text label that says “Download”, the icon takes alt="". Describing it too means the user hears “Download Download”.

Can a tool check your alt text?

It can check that the attribute exists. It cannot check that the words are any good, and that gap is the whole problem.

This is the rule where the limits of automation are clearest, and I ran into it directly building RedFlag’s image rules. A scanner can detect with total reliability that an alt attribute is absent. It can flag the obvious junk patterns: a filename, a bare extension, the word “image” on its own, alt text identical to the caption beside it. What it cannot do is read alt="Bar chart showing quarterly results" and know whether the chart actually shows quarterly results, or whether that sentence is the thing the reader needed.

That is why the alt text rule is written as an automated check for presence with a manual step for quality. Of the 122 rules RedFlag ships, 26 work this way, and image alternatives are the clearest example of why that split has to exist. A tool that reported “alt text: pass” for a page full of alt="image" would be technically correct and completely useless.

The practical consequence: automation gets you to every image having an attribute, which is real progress and usually a large number of fixes. Getting from there to alt text worth listening to is a human pass, and it is quick once the attribute audit is done.

How do I check my own alt text?

Two passes, neither of which takes long.

First, scan for absence. Missing attributes are found mechanically and there is no reason to look for them by hand. Run a scan over your key pages and fix every image the tool flags.

Then read the page with the images turned off, or listen to it. Ask one question of each description: if I could not see this image, would this sentence give me what the image was carrying? Most bad alt text fails that question immediately, and the fix is usually obvious once the question is asked.

If you want the fastest possible version, turn on a screen reader and pull up the images list. It makes the failures audible in a way that reading markup never does, and filename soup is unmistakable when you hear it.

Frequently asked questions

What is alt text?

The value of the alt attribute on an HTML image, read aloud by a screen reader in place of the image and shown if the image fails to load. It is how a person who cannot see the picture gets whatever information the picture was carrying, and it is required by WCAG success criterion 1.1.1.

How long should alt text be?

Long enough to carry the information and no longer, which in practice is usually one sentence. There is no hard limit in the specification, but screen readers announce it as a single uninterrupted block, so a paragraph is punishing to listen to. If an image genuinely needs a paragraph, put that description in the page text and give the image shorter alt.

When should alt text be empty?

When the image is decorative, meaning it adds no information the surrounding text does not already carry. Dividers, background flourishes and icons sitting next to a text label that already says the same thing all take alt="". The empty string tells assistive technology to skip the image, which is what you want. Leaving the attribute off entirely is different and worse.

Should alt text include keywords for SEO?

Write it for the person listening and the search benefit follows. Alt text does help Google understand an image, but stuffing keywords produces text that is useless to a screen reader user and has been discounted by search engines for years. An accurate description is the version that serves both.