Alt text is the short text in an image's alt attribute that stands in for the picture: a screen reader speaks it, a browser shows it when the image fails to load, and search engines read it to understand what the image shows. Good alt text says what a visitor who cannot see the image would miss, in one sentence, and says nothing at all (alt="") when the image is only decoration.
The hard part is not the attribute but the decision: the same photo can be decorative on the home page, informative on a product page and functional inside a link. This guide gives you the decision in five questions, worked alt text examples to copy the reasoning from, and where the field lives in WordPress and Shopify. Alt text is one of the ten fixes in the web accessibility guide.
Quick answer
| The image… | Kind | What to write |
|---|---|---|
| adds nothing the text next to it does not say | Decorative | alt="" (empty, not missing) |
| carries information the text does not | Informative | One sentence on what it shows and why it is there |
| is the only content of a link or button | Functional | The destination or action: "Search", "Example Shop home" |
| is a chart, diagram or map | Complex | A short alt with the conclusion, plus the data in text nearby |
| contains words | Image of text | The words, verbatim |
| is one of several that form one message | Group | One alt on the first image, alt="" on the rest |
- Never leave
altout entirely: a missing attribute makes screen readers read the file name. - Skip "image of" and "picture of"; the screen reader already says "image".
- No tool can tell you which row an image belongs in. Checks find missing and empty alts; the decision is yours.
What alt text does, and who reads it
For a blind or low-vision visitor, the alt text is the image. A product page with six photos and no alt text is six announcements of "IMG_4412.jpg". A "Buy now" button made of an image with no alt is a button with no name. The World Health Organization estimates that about 1 in 6 people live with a significant disability. WCAG 2.2 criterion 1.1.1 Non-text Content, level A, asks for a text alternative that "serves the equivalent purpose"; purpose is the word that matters.
For search, Google's image SEO guidance says it uses alt text together with computer vision and the page's content to understand an image, and warns against keyword stuffing. When an image is a link, Google treats its alt as the link's anchor text. A photo with alt="Tan leather weekender bag, side view" can appear in image search for "tan leather weekender"; the same photo with no alt gives far less to go on. Both readers want the same thing: an honest description, in context.
How to write alt text: five questions
The W3C's alt decision tree asks its questions in a fixed order. Ask them about each image in its context and stop at the first yes:
- Does it contain text? If the same text is in the HTML nearby,
alt="". If not, the alt is the text. - Is it inside a link or button, and would the purpose be unclear without it? It is functional: the alt names the destination or action.
- Does it add meaning? A photo or simple graphic gets a short description; a chart or diagram gets a short alt plus a longer description in the page.
- Does it repeat what the text next to it says, or is it pure decoration?
alt="". - Still unsure? Ask what a visitor loses if the image disappears: nothing, information, or a way to act.
Then write it like a caption on a phone call: when you reach the image, what would you say? Usually one sentence, with the most important detail first and a full stop at the end so the screen reader pauses. There is no hard length limit; many style guides suggest staying under about 125 characters, and anything that needs a paragraph belongs in the page text instead.
Alt text examples, by kind
Decorative: be strict
Dividers, background flourishes, a stock photo of a handshake above "Contact us", an envelope icon next to the word "Email". Empty alt tells the screen reader to skip it; a missing attribute tells it "I do not know", and it falls back to the file name:
<img src="/img/wave-divider.svg" alt="">Informative: what matters, in context
<img src="/img/weekender-tan-side.jpg" alt="Tan leather weekender bag, side view, brass zip">What goes in depends on why the image is there: for a product photo, what distinguishes this view; for a screenshot, what the reader should notice; for a portrait, who, and doing what if it matters.
Functional: name the action, not the picture
When an image is the only content of a link or button, its alt becomes the link's or button's name:
<a href="/"><img src="/img/logo.svg" alt="Example Shop home"></a>
<a href="https://www.instagram.com/exampleshop/"><img src="/img/ig.svg" alt="Example Shop on Instagram"></a>
<button type="submit"><img src="/img/magnifier.svg" alt="Search"></button>If the link also contains visible text ("Example Shop" next to the logo), the image gets alt="" so the name is not read twice. A functional image with no alt is also a link with no name; accessible names for links and buttons covers that side.
Icons and inline SVG
Icon fonts and inline SVG are not <img>, so they have no alt. Hide the icon and name the control:
<button type="button" aria-label="Close">
<svg aria-hidden="true" focusable="false" width="16" height="16"><use href="#icon-x"></use></svg>
</button>An inline SVG that carries meaning on its own needs a role and a name:
<svg role="img" aria-labelledby="map-title" viewBox="0 0 400 300">
<title id="map-title">Map: the shop is on Ilica 12, two minutes from the main square</title>
<!-- paths -->
</svg>Decorative inline SVG gets aria-hidden="true". An SVG with role="img" and no name is reported by axe's svg-img-alt rule, under serious violations.
Complex images: short alt, long description in the page
A chart's alt says what it is and what it shows; the data goes in the page, where sighted readers benefit too:
<figure>
<img src="/img/lcp-2026.png"
alt="Line chart: LCP fell from 4.2 s in January to 1.8 s in June"
aria-describedby="lcp-data">
<figcaption>Largest Contentful Paint, 75th percentile, 2026.</figcaption>
</figure>
<table id="lcp-data">
<caption>Monthly LCP, 75th percentile</caption>
<tr><th scope="col">Month</th><th scope="col">LCP</th></tr>
<tr><td>January</td><td>4.2 s</td></tr>
<tr><td>June</td><td>1.8 s</td></tr>
</table>aria-describedby points the screen reader at the longer content without making the alt long.
Groups, images of text and backgrounds
- Groups. Five star images meaning "4 out of 5 stars" get that alt on the first and
alt=""on the other four. A product gallery gets a different alt per photo, saying what each view shows. - Images of text. A banner saying "Free shipping over 50 €" gets exactly those words. Better: put the text in HTML over the image.
- CSS background images cannot have alt. Fine for decoration; if a background carries meaning (the product in the hero), move it to an
<img>or put the meaning in text.
Worked examples
| Image and context | Alt |
|---|---|
| Logo in the header, links home | Example Shop home |
| Same logo in the footer, not a link, next to the text "Example Shop" | alt="" |
| Main product photo on a product page | Navy rain jacket with the hood up, front view |
| Third gallery photo, showing the lining | Inside of the jacket: mesh lining and zipped chest pocket |
| Product thumbnail in a category grid, name linked below it | alt="" |
| Magnifier icon, only content of the search button | Search |
| Hero photo of a beach behind the heading "Summer sale" | alt="" |
| Banner image "Free shipping over 50 €", no HTML text | Free shipping over 50 € |
| Bar chart of monthly orders in a blog post | Bar chart: orders doubled between March and May, plus a data table |
| Team photo on the About page | The six-person team outside the Zagreb workshop |
| Five star icons under a review | First: Rated 4 out of 5; the rest: alt="" |
Keyword stuffing (alt="leather bag leather bags buy leather bag online") is read aloud, word for word, to a person, and it is what Google's guidance says not to do. AI tools can draft a description, but they do not know why the image is on this page; review every draft against the five questions.
How getReport checks it
The SEO audit reads every <img> in the HTML as served, before scripts run. It counts images with no alt attribute at all (a failure) and lists images with alt="" for review, by file name, because empty is right for a divider and wrong for a product photo.
The accessibility checker looks at the rendered page in Chromium with axe-core's image-alt, input-image-alt and role-img-alt rules, so it also covers images added by JavaScript, image buttons and elements with role="img". axe accepts any accessible name (alt, aria-label, aria-labelledby, title) and role="presentation" for decoration, and lists CSS selectors rather than file names.
The two angles differ on purpose. An <img> with a title but no alt passes axe and fails the SEO count; an image added by a slider script appears only in the axe result. In the report's Top fixes, the two count as one cause, so you see one fix, not two.
Where to set alt text
WordPress. Media → Library → click the image → Alternative Text. The value is copied into an Image block when you insert the image; editing the library later does not change blocks already placed, so old posts need the block edited too (select the block, Settings sidebar, Alternative text). Featured images, WooCommerce product galleries and theme-rendered images read the library value each time.
Shopify. Products → the product → click an image → Add alt text, one per gallery image. Theme images (logo, banners, slideshow) have an alt field per image block in the theme editor; collection images are set on the collection.
Squarespace and Webflow. Squarespace's alt field differs by block type, and some blocks fall back to the caption or file name. Webflow keeps an alt per asset, and each placed image can override it or be marked decorative. Check the published page.
Markdown and templates. ;  gives an empty alt. A build-time check that fails on <img> without alt catches regressions before they ship.
Verify
- The SEO audit reads "Every image has an alt attribute", and the decorative list contains only images you chose to mark decorative.
- The accessibility checker reports "Every image has alternative text".
- With images turned off, the page still reads: product names, the logo's name, the button labels.
- A screen reader pass over one product page (testing with a screen reader): "Image, tan leather weekender bag, side view" is right; "DSC underscore four four one two dot JPG" is a missing alt; silence where a product photo should be is an empty alt on an informative image, the trap no tool catches.
Common mistakes
- No attribute at all. Screen readers read the file name. Add
alt, empty or not, to every<img>. - Empty alt on a product photo. The audit passes and your best images never appear in image search. Describe them.
- Alt on decorative images. "Blue wave divider" read between every section. Use
alt="". - The same alt on every gallery image. Six photos announced as "Rain jacket". Say what each view shows.
Questions people ask
What is alt text?
Alt text is the text alternative for an image, written in the alt attribute of the <img> tag. Screen readers speak it in place of the image, browsers show it when the image fails to load, and search engines use it to understand the picture. It should say what the image means on the page in one sentence, or be empty for decoration.
How do you write alt text for a product photo?
Describe what distinguishes this photo from the others: the product name, colour, material and the view shown, such as "Navy rain jacket, hood up, back view". Give each gallery image its own alt. Leave out "image of", prices and keyword lists, and put anything longer, like the size chart, in the page text instead.
Should decorative images have empty alt text?
Yes. A purely decorative image should have alt="", an empty attribute, so screen readers skip it silently. Do not remove the attribute: with no alt at all, many screen readers read the file name instead. Be strict about what counts as decorative; if removing the image would lose any information, describe it.
What is the difference between alt text and a caption?
Alt text replaces the image for people who cannot see it and is hidden from everyone else. A caption, usually in <figcaption>, is visible to all and adds context such as a source, date or credit. They should not repeat each other; when the caption already describes the image fully, the alt can be short or empty.
Can AI write alt text for my images?
AI can draft a description, but it cannot know why the image is on your page, which is what decides the alt. It may describe a decorative photo in detail or miss the one detail a product photo is there to show. Use AI drafts as a starting point and check each against the page's purpose.
Does every image need alt text?
Every <img> needs an alt attribute, but not every image needs words in it. Decorative images get alt="", and images whose content is already in nearby text can too. CSS background images cannot have alt at all, so never use them for pictures that carry meaning.