Skip to main content

"Images must have alternative text": how to write alt text for your website

Published · Updated

“Images must have alternative text” is the error you’ll see in axe. Lighthouse calls it “Image elements do not have [alt] attributes”, WAVE calls it “Missing alternative text”, and the Tabwise scan calls it “Images are missing a text description”. They all mean the same thing.

Alt text is a short written description of an image. Screen readers read it aloud to people who can’t see the picture, and it shows up if the image doesn’t load. This guide shows you how to write alt text that actually helps, with examples for real types of business.

About one in five Irish business websites we tested (22% of 6,576) had images with no alt text at all. Among Shopify stores it was one in four, according to our study of Irish Shopify stores (26% of 1,004).

Who this affects

Alt text is mainly for people who use a screen reader. That’s software that reads the page aloud, used by blind people and many people with low vision.

Without alt text, a screen reader might say “image”, or read out the file name, like “IMG underscore 4471 dot jpg”. If that image is your product photo, your customer has no idea what you’re selling.

Google uses it to understand your images too.

Why it happens on so many sites

  • Photos uploaded in a hurry. Most builders let you add a photo without a description, and never remind you.
  • Theme banners and slideshows. The big images at the top of your homepage are set up in theme settings. The alt text field there is easy to miss.
  • Product imports. Products copied in from a supplier’s spreadsheet often come with no image descriptions.

There’s a catch in our figures. Our scans can only tell whether alt text is there, not whether it makes sense. Alt text that says “image1” or “photo” passes a scanner but helps nobody. So the real picture is worse than 22%.

Squarespace is a good example. If you leave a product image’s alt text blank, it uses the product name instead. That passes a scanner, but “Wool scarf” tells a screen reader user much less than a good description would.

How to write alt text

Ask yourself: if I described this image to someone over the phone, what would they need to know? Write that, in a sentence or less.

Leave out “image of” or “photo of”. Screen readers already say it’s an image.

Examples by type of business

A product photo in an online shop

  • Not helpful: “Scarf”
  • Better: “Chunky knit wool scarf in forest green, with tassels at both ends.”

Say what makes this product different from the one beside it: colour, material, pattern.

A team photo on a dental practice website

  • Not helpful: “Team photo”
  • Better: “Our dentists and nurses, five people in blue scrubs, smiling in the reception area.”

If names matter, put them in a caption everyone can read.

A photo of your café’s menu

  • Not helpful: “Menu”

This one is a real problem, and alt text can’t solve it on its own. A menu has dozens of items and prices. That won’t fit in alt text, and nobody wants to hear it read in one breath. See the menu section below.

A hotel or B&B room

  • Not helpful: “Room 4”
  • Better: “Double room with a large bay window looking out over the harbour.”

How long it should be

Keep it short: one sentence, about 125 characters at most. That’s Shopify’s own recommendation.

When to leave alt text empty

Some images are just decoration: a swirl, a background texture, a stock photo of coffee beans that adds nothing. These should have empty alt text, so screen readers skip them.

Empty is not the same as missing. Some builders, such as WordPress, let you mark an image as decorative. Use it rather than leaving the field blank and hoping.

If an image is a link, such as your logo, describe where it goes, not what it looks like. Our guide to links with no name covers this.

The trouble with photos of menus and price lists

A photo of your menu, price list or opening hours causes trouble. Screen readers can’t read it, it’s hard to read on a phone, and Google can’t see it.

The real fix is to type the menu onto the page as normal text. Then keep the photo if you like, with short alt text such as “Our printed lunch menu. The full menu is written out below.” Our guide to restaurant, café and pub websites covers menus, allergens and opening hours in more detail.

How to fix it

Shopify

For product photos, go to Products in your Shopify admin and open the product. Click a photo, click Add alt text, type your description and click Save alt text. Shopify’s guide to adding alt text to product media has the full steps. Its media editor can suggest alt text using AI. Read every suggestion before you save it.

For banners and slideshows, open the theme editor, click the section with the image, and click Edit on the image.

WordPress and WooCommerce

Go to Media, then Library, and click an image. Fill in the Alt Text field. This sets the default whenever the image is used, including WooCommerce product photos.

In the block editor, the Image block has an Alternative text field and a “Mark as decorative” option. Alt text added there only applies to that one page. WordPress explains this in its Image block guide.

Wix

Click the image, click the Settings icon, and type your description under “What’s in the image?”. Wix’s guide to preparing your images covers galleries too.

To mark an image as decorative, use Wix’s Accessibility Wizard. It also finds every image on your site that’s missing alt text.

Squarespace

For an image block, edit the block and use the “Image alt text” field. For product images, open the image’s Edit metadata option and fill in Alt text. Squarespace’s guide to adding alt text to images has the steps for each type of image.

If someone else built your site

Copy this and send it to your web person:

Some images on our website have no alt text, which fails WCAG 2.1 AA (success criterion 1.1.1). Can you show me where to add alt text myself, and mark purely decorative images so screen readers skip them? Please check the theme’s banner and slideshow images too.

How to check it’s fixed

Run our free scan again. It finds images with no alt text. It checks your homepage and up to four pages linked from it. It can’t tell you whether your alt text is any good, though.

For that, try reading your alt text out loud with your eyes closed. Would a customer on the phone know what the picture shows? If not, rewrite it.

The W3C’s alt text decision tree helps with tricky images. Nielsen Norman Group’s article Alt Text: What to Write has more examples.

For your web developer

The rule is WCAG 2.1 success criterion 1.1.1, Non-text Content. axe reports missing alt text as image-alt.

  • Every <img> needs an alt attribute. Decorative images get an empty one, alt="", so screen readers skip them. A missing alt is a failure.
  • Don’t rely on the title attribute. Many screen readers and most touch devices ignore it.
  • Check theme sections and app blocks where the image comes from a setting rather than the media library. Make sure the theme outputs the alt text the owner enters.
<!-- Informative -->
<img src="scarf-green.jpg"
     alt="Chunky knit wool scarf in forest green, with tassels at both ends.">

<!-- Decorative -->
<img src="divider.svg" alt="">

Check your own website for free

We'll scan your homepage and a few key pages and email you a plain-English report in minutes.

Free Report by email in minutes Privacy