Skip to content
pageinspection

Image alt text: what to write, and when to write nothing

There are three states an image can be in, and most tools only report two. It can describe itself, it can declare that it has nothing to say, or it can be silent. The first two are correct. Only the third is the defect, and conflating the last two is why alt-text audits produce so much busywork.

The short answer

Alt text has two correct uses: describing what the image conveys, or being deliberately empty when the image conveys nothing. An empty alt on a decorative image is correct and a missing alt attribute is not, because a screen reader falls back to reading the filename. Describe the function, not the appearance.

ImportantAudit check · Image alt text

The attribute has two correct uses

alt="Bar chart showing revenue doubling in Q3" and alt="" are both right answers to different questions. The first describes content. The second states, deliberately and machine-readably, that this image carries no information and should be skipped.

Omitting the attribute entirely is different from both. It leaves the question unanswered, and assistive technology has to fall back on something, usually the filename. A screen reader announcing "i-m-g underscore 4 7 2 1 dot j p g" is the failure this check exists to prevent, and it is strictly worse than silence.

What is counted, and what cannot be

Every <img> in the rendered markup, counted, and how many of them have no altattribute at all. An empty alt counts as present, because it is a valid declaration rather than an omission. The report is a ratio rather than a boolean, since "two of forty" and "forty of forty" are different problems with different causes.

What it cannot measure is quality. alt="image", alt="photo" and alt="widget-final-v2" all pass a presence check and all fail a human. No crawler can score that, and any tool claiming to is guessing.

Check one page for images missing alt text

Paste a URL. This reports how many images the page renders and how many of them have no alt attribute, which is the part that can be measured mechanically.

Check one page for images missing alt text

No signup required. Each free search audits one page, paste any URL to see it in action.

What to write, and the test for whether you got it right

The working test: if you replaced the image with your alt text, would the page still make sense? Not "does this describe the picture" but "does this do the job the picture was doing". Those come apart most obviously on charts and on images inside links.

alt-text.html
<!-- Describes the file, not the content. -->
<img src="chart-q3.png" alt="chart">

<!-- Redundant: the caption already says this, so a
     screen reader user hears it twice. -->
<img src="chart-q3.png" alt="Revenue chart">
<figcaption>Revenue chart</figcaption>

<!-- Carries the information the image carries. -->
<img src="chart-q3.png"
     alt="Revenue doubled between July and September,
          then held flat through Q4.">

<!-- Inside a link, the alt IS the link text. Describe
     the destination, not the picture. -->
<a href="/pricing">
  <img src="arrow.svg" alt="See pricing">
</a>

<!-- Purely decorative. Empty alt is correct and
     deliberate: it tells the screen reader to skip. -->
<img src="corner-flourish.svg" alt="" aria-hidden="true">

Two rules do most of the work. Do not start with "image of" or "picture of", because the technology already announces that it is an image. And never repeat a caption verbatim: if a <figcaption> already says it, the alt should add what the caption leaves out or be empty.

Decorative images, and the pages that are all decoration

On a marketing page, a large share of images genuinely carry no information: gradients, dividers, texture, the abstract shape behind a heading. Every one of those should have an empty alt, and writing descriptions for them makes the page measurably worse to listen to.

This is where the check's ratio matters. A page reporting forty of forty images missing alt is usually a template that never emits the attribute, and the fix is one component. A page reporting two of forty is usually two hand-inserted images in body content, and the fix is editorial. Same check, completely different work.

An icon next to text that already says the same thing is decoration.

A download icon beside the word "Download" needs alt="". Give it alt="download icon"and a screen reader user hears "download" twice, which is the most common over-correction on this check.

Where the attribute goes missing, by platform

WordPress
The media library has an alt field and the editor does not require it, so the value depends entirely on whether whoever uploaded the file filled it in. Worse, the field is attached to the library item rather than to its use, so the same image used decoratively in one place and informatively in another gets one description for both.
Shopify
Product images take their alt from the image alt field, which is empty by default on bulk imports and CSV uploads. A store with a thousand products imported from a supplier feed typically has a thousand images with no alt text and no practical way to write them by hand.
Next.js and React
next/image requires the alt prop, and the standard ESLint rule flags a missing one, so a well-configured project fails at build rather than in production. The gap here is usually a wrapper component that accepts an optional alt prop and defaults it to an empty string, which silently converts every informative image into a decorative one.
Rich-text and CMS body content
Anything pasted from a document editor arrives with no alt attribute, and images inserted by editors in a WYSIWYG field are the single most common source of a low missing-count on an otherwise clean site.

Why an accessibility failure is rated Important

It is an accessibility failure with a named cost: a user of assistive technology gets a filename instead of information. That alone would justify the rating without any search argument attached to it.

It is not Critical because nothing structural breaks. The page indexes, ranks and renders. And it is not Refinement because, unlike most polish items, someone is concretely worse off when it is wrong. The scale treats a real harm to a real user as Important even when no ranking moves.

Confirming coverage

The fastest manual check is to disable images in your browser and read the page. What you are left with is roughly what a text pipeline gets, and a page that becomes incomprehensible is a page whose alt text is not doing its job even where the attribute is present.

Re-crawl to confirm the count. The ratio moving to zero is the mechanical pass. Whether the text you wrote is worth reading is the part that needs a person, and it is worth spending that attention on the handful of images that actually carry an argument rather than spreading it across every gradient on the site.

Questions this check raises

Is an empty alt attribute a mistake?
No, it is the correct markup for a decorative image. alt="" tells a screen reader to skip the element entirely, which is what you want for a background flourish or a spacer. Omitting the attribute is the mistake: with no alt at all, the screen reader falls back to announcing the filename.
What should alt text say?
What the image conveys in context, in the shortest form that conveys it. For a product photo, the product. For a chart, the finding rather than the chart type. The test is whether replacing the image with your alt text leaves the page making the same point.
Does alt text help SEO?
It is how image search understands the image, so it helps there directly. On the page itself the effect is small and easily overdone: keyword-stuffed alt text is a recognised spam signal and it makes the page worse for the people the attribute exists to serve. Write it for a screen reader and the search benefit follows.