"Images must have alternate text": how to fix missing alt text in your app
"Images must have alternate text" means an <img> on your page has no alt attribute, so screen readers have nothing to say about it and may read out the file name instead.
Give every meaningful image a short alt that says what it shows or does, and give purely decorative images an empty alt="" so screen readers skip them.
Why it matters
The axe rule image-alt says: "All images must have alternate text to convey their purpose and meaning to screen reader users." It maps to WCAG success criterion 1.1.1 Non-text Content, Level A.
The US Department of Justice's web guidance lists missing alt text among common barriers: images without a text alternative leave blind users unable to understand their content or purpose. The same guidance says the Department has consistently taken the position that the ADA's requirements apply to goods and services that businesses open to the public offer on the web.
Which alt to write
| Image | Alt text |
|---|---|
| Product photo | alt="Blue ceramic mug, 12 oz, with a wooden handle" |
| Logo that links home | alt="Acme Rota home" (say where the link goes) |
| Icon inside a labeled button | alt="" (the button's text already names it) |
| Background flourish, divider, stock mood photo | alt="" |
| Chart or screenshot with data | A short summary, with the details in the page text |
Two rules of thumb: describe the purpose, not "image of", and keep it to a sentence. An empty alt="" is a deliberate choice that says "decorative"; leaving alt out entirely is the error.
<img src="/hero.webp" alt="Team rota on a phone, showing this week's shifts">
<img src="/swoosh.svg" alt="">
Fixing it in an AI-built app
Ask your builder:
Find every <img> (and image components) in the app. Add a short, specific
alt attribute that says what each meaningful image shows or does. For
purely decorative images, set alt="". Don't start alt text with "image of".
List the images you changed with the alt text you chose.
Then read the list: a builder can't know what your product photo shows better than you do.
How to check your own pages
Run an accessibility checker such as axe DevTools or Lighthouse's accessibility audit in Chrome, or open the page and inspect each image's alt in the Elements panel.
What Pewterkit Check looks for
A free check reads your homepage's server HTML and counts <img> elements with no alt attribute. When the server HTML is an empty app shell (common for single-page apps), it makes no claim, because the images only appear after JavaScript runs.
FAQ
What's the difference between alt="" and no alt?
alt="" tells screen readers the image is decorative, so they skip it. With no alt at all, W3C's images tutorial warns that "some screen readers will announce the file name of the image instead".
How long should alt text be?
Short: usually one sentence that says what the image shows or does in context. Put long descriptions, such as chart data, in the page text.
Does alt text help SEO too?
It does: Google says it combines alt text with computer vision and the page content to understand an image, and warns against filling alt attributes with keywords. Write it for people first.
My builder says the images are added by JavaScript. Does that matter?
The fix is the same: set alt where the image component is rendered. Rendered-page checkers such as axe DevTools see JavaScript-added images.
Sources
- W3C WAI Images Tutorial: Decorative images — read 27 Oct 2026: null alt="" for decorative images, missing alt can announce the file name
- axe rule image-alt: Images must have alternate text (Deque University) — read 27 Oct 2026: rule text, decorative alt="", WCAG 1.1.1
- Guidance on Web Accessibility and the ADA (ADA.gov, U.S. Department of Justice) — read 27 Oct 2026: missing alt text as a barrier, ADA applies to the web
- Google Search Central: Google Images best practices — read 27 Oct 2026: how Google uses alt text, no keyword stuffing
How this page was made: drafted with AI from the sources listed, reviewed by Pewterkit. Docs checked Oct 27, 2026. Spotted something out of date? Tell us.