OnlineNexusAccess accessibility home Free scan

How to add alt text to WooCommerce product images (one by one, in bulk and in code)

Alt text is the short description a screen reader reads out in place of an image. On a product page it can be the difference between "image" and "Navy linen shirt, front view, button-down collar". WooCommerce stores alt text in the WordPress Media Library, which means you set it once per image and every product that uses that image benefits. This guide covers where to add it, how to find every image that is missing it, and what to write.

Where WooCommerce keeps alt text

Product images and gallery images are ordinary WordPress media attachments (Adding product images and galleries (WooCommerce documentation)). Each attachment has an Alternative Text field, saved in the database as the _wp_attachment_image_alt post meta. When a theme prints an image with WordPress's standard functions, it reads that field and puts it in the alt attribute.

Two consequences:

  • Alt text belongs to the image, not the product. If the same photo is used on two products, it has one alt text.
  • Typing a caption or a title is not the same thing. The image title and caption fields are separate, and most themes don't use them as alt text.

Adding alt text one image at a time

  1. Go to Media > Library and switch to list view for a faster overview.
  2. Click an image to open its details. Fill in Alternative Text, not Title or Caption.
  3. Changes save automatically in the grid view's details pane; in the list view's edit screen, click Update.

You can also do it from the product: in Products > Edit, click the product image or a gallery image, and the same Alternative Text field appears in the media window. The WordPress documentation for the Image block covers alt text for images inside your page content (Image block (WordPress.org documentation)).

Finding every image that is missing alt text

On a store with hundreds of products, clicking through the library is slow. If your host gives you WP-CLI (many managed WordPress hosts do), this one command lists every image attachment whose alt text is missing or was saved empty, using WordPress's own query functions through wp eval (wp eval (WP-CLI command reference)):

Terminal (WP-CLI): list images missing alt text
wp eval '
$ids = get_posts( array(
    "post_type"      => "attachment",
    "post_mime_type" => "image",
    "posts_per_page" => -1,
    "fields"         => "ids",
    "meta_query"     => array(
        "relation" => "OR",
        array( "key" => "_wp_attachment_image_alt", "compare" => "NOT EXISTS" ),
        array( "key" => "_wp_attachment_image_alt", "value" => "", "compare" => "=" ),
    ),
) );
echo "id,parent_id,file" . PHP_EOL;
foreach ( $ids as $id ) {
    echo $id . "," . wp_get_post_parent_id( $id ) . "," . basename( get_attached_file( $id ) ) . PHP_EOL;
}
' > missing-alt.csv

The parent_id column is the ID of the product (or page) the image was first uploaded to, which helps you work out what each image shows. Open the CSV file in a spreadsheet, write the alt text for each row, then set it, one command per image (wp post meta update (WP-CLI command reference)):

Terminal (WP-CLI): set alt text for one image
wp post meta update 1234 _wp_attachment_image_alt "Navy linen shirt, front view, button-down collar"

Take a database backup before bulk changes, and try a few images first. If you don't have WP-CLI, several Media Library plugins add an editable alt text column to the list view; read their reviews and recent update dates before installing.

Should you auto-fill alt text with the product name?

Some plugins and code snippets fill every empty alt attribute with the product title. It removes the scanner warning, but it is rarely a good description: a gallery of six photos all announced as "Navy linen shirt" tells a blind shopper nothing about what differs between them. Automated tools also flag image descriptions that just repeat nearby text (image-redundant-alt); in our 10-store test sample one store had 24 of these. Use auto-fill, if at all, only as a temporary stopgap while you write real descriptions.

Check what your theme actually outputs

Adding alt text in the library only helps if your theme prints it. Open a product page, right-click the main image, choose Inspect, and look at the <img> tag. If the alt attribute is missing or empty even though you filled in the field, the theme (or a gallery or slider plugin) is building the image itself.

If you maintain a custom template, use WordPress's image functions, which read the stored alt text for you:

your-child-theme/woocommerce/single-product/your-template.php (excerpt)
<?php
// Prints the image with the alt text saved in the Media Library.
echo wp_get_attachment_image( $attachment_id, 'woocommerce_single' );

// If you must build the tag yourself, read the alt text explicitly:
$alt = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
printf(
    '<img src="%s" alt="%s" width="%d" height="%d">',
    esc_url( wp_get_attachment_image_url( $attachment_id, 'woocommerce_single' ) ),
    esc_attr( $alt ),
    600,
    600
);

Purely decorative images, such as background flourishes, should have an empty alt attribute (alt="") so screen readers skip them. Leaving the attribute out completely is different: many screen readers then read the file name instead.

To check a page once you have made changes, paste its HTML into our free alt text checker.

Check your own store in a minute or two. Our free scanner opens your homepage, a collection page, a product page and your cart in a real browser and lists the problems it can detect automatically, in plain English.

Run the free scan

What to write

The W3C's alt decision tree is a quick way to decide whether an image needs a description and what kind (An alt Decision Tree (W3C WAI)). For product photos, describe what a shopper would want to know from that particular image:

  • Main product photo: the product and its key visible features. "Handmade soy candle in a frosted amber glass jar with a wooden lid."
  • Gallery photos: what this view adds. "Same candle, lid off, showing the cotton wick." "Size comparison: candle next to a coffee mug, about the same height."
  • Colour or variant photos: name the variant. "Sage green version."
  • Images containing text, such as a sale banner: include the text. "Autumn sale: 20% off all candles until 30 November."

Skip "image of" or "photo of"; screen readers already say it's an image. Keep most descriptions to one sentence. The WP Accessibility Knowledge Base has more examples (Alt text for images (WP Accessibility Knowledge Base)).

Keep it from slipping again

Make alt text part of adding a product: whoever uploads photos writes the descriptions at the same time. Re-run the WP-CLI query or our free scan once a month to catch new images without it. If you also sell on Shopify, our Shopify alt text guide covers the same job there.

Common questions

Does alt text help SEO as well?

Search engines read alt text to understand images, so good descriptions can help product photos appear in image search. Write for people first, though: stuffing keywords into alt text makes it worse for screen reader users and doesn't help them choose a product.

What about images in product descriptions?

Images you insert into a product description or a page through the block editor have their own alt text field in the Image block's settings sidebar. Images added there from the Media Library start with the library's alt text, but you can change it per block.

Will a plugin that "generates" alt text with AI do the job?

It can give you a first draft faster, but check every result. Generated descriptions often miss what matters for a sale, such as the fabric, the size or which colour variant is shown, and sometimes get details wrong.

What about images in product descriptions and blog posts?

Images you insert into a product description, a page or a post through the WordPress editor have their own alt text field in the block or media settings, and they use the same Media Library entry as above. If you inserted an image before you added its alt text, check the block itself: some older content keeps the alt text it had when the image was first inserted, so update it there too.

Technical fixes, not legal advice. This guide explains website accessibility from a technical point of view. We are not a law firm, and nothing here is legal advice. No scan, fix or guide can guarantee legal compliance, the outcome of any demand letter or lawsuit, or protection from future claims. If you have received a legal claim, please consult a qualified attorney about it.

Sources