# WooCommerce variation galleries in production catalogues

WooCommerce 11.1 puts per-variation image galleries in core. How I migrate Additional Variation Images and test furniture and footwear PDPs.

- Date: 2026-09-17
- Category: WooCommerce

WooCommerce variation galleries are now the core way a variable SKU shows a full image set when a shopper picks a colour or size, not a paid extra. I am Alan Vo, a Gold Coast web developer with 18 years on catalogues. In 2026 WooCommerce 11.1 turns that gallery on for every store, retires the Additional Variation Images extension, and expects the Product Gallery block to follow the variation.

WooCommerce documents the merchant path in [variable products](https://woocommerce.com/document/variable-product/) and the migration in the [Additional Variation Images note](https://woocommerce.com/document/woocommerce-additional-variation-images/). The [11.1 release notes](https://developer.woocommerce.com/2026/09/03/wc-11-1-release-notes/) and the [developer advisory](https://developer.woocommerce.com/2026/09/01/additional-variation-images/) are the facts I use on furniture and footwear PDPs. I already keep the PDP spine in [WooCommerce product page blocks](https://alanvo.com/blog/woocommerce-product-page-blocks/) and the shop grid on the [WooCommerce Product Collection block](https://alanvo.com/blog/woocommerce-product-collection-block/). Variation galleries sit between those two: merchandising owns the photos, the template has to swap them without a custom slider.

## Why WooCommerce variation galleries matter in 2026

WooCommerce variation galleries matter in 2026 because a variable product can now carry an ordered gallery on each variation, and every 11.1 store gets that behaviour whether anyone ticked a Features box or not. WooCommerce 10.9 shipped the feature behind a Variation gallery toggle. 11.1, released 1 September 2026, turns it on for all stores, removes the toggle, and runs a database update (`11.1.0-1`) that enables it even on shops that had opted out.

That is a catalogue change, not a theme nicety. A sofa in oak and walnut used to get one featured image per variation unless you paid for Additional Variation Images or wrote a custom gallery. Core now stores those extra IDs on the variation. The standalone extension is deactivated on upgrade. WooCommerce retired it on 5 September 2026. WordPress will refuse to activate it again.

I treat the upgrade as a PDP release. Photographers already shot four angles per colour. The storefront was throwing three of them away. 11.1 is the first time I can attach that set without an extra plugin.

Colour / Image attributes and core color swatches are a separate 10.9 flag. They only paint the Add to Cart + Options (Beta) picker. The gallery swap still has to work if merchandising never creates a `wc-visual` attribute. Product gallery videos in 11.1 are experimental, local Media Library files only, and off by default. I leave that flag off on a furniture LCP.

## How WooCommerce variation galleries actually work

WooCommerce variation galleries actually work as an ordered list on each variation: a primary image plus extra gallery IDs, swapped onto the product gallery when the shopper selects that variation, then restored to the parent gallery when they clear the selection. WooCommerce walks through that on the [variable product screen](https://woocommerce.com/document/variable-product/). Open Products, edit the variable product, open Variations, expand a row. The blue placeholder is still the primary image. Manage next to Variation gallery opens the rest. Drag to reorder. The first image becomes primary. Save changes on the Variations tab, not only Update on the product.

![WooCommerce variation galleries checkout fields on a laptop in a studio](../../images/blog/woocommerce-variation-galleries-1.jpg)

Storage is `_product_image_gallery` on the variation, the same postmeta key parent products already use. The `wc/v3` field is `gallery_image_ids`, extra attachments only. The featured image stays in `image`. WooCommerce documents both on the [product variations REST API](https://developer.woocommerce.com/docs/apis/rest-api/v3/product-variations/). PHP should go through `WC_Product_Variation::get_gallery_image_ids()` and `set_gallery_image_ids()`, or the `woocommerce_product_variation_get_gallery_image_ids` filter. Direct writes to `_wc_additional_variation_images` are leftover extension data. Core no longer writes back to that key.

On the storefront, `woocommerce_available_variation` includes `gallery_image_ids` and `gallery_images_html`. Classic themes should listen to `show_variation` and `reset_data`. The old Additional Variation Images events, including `wc_additional_variation_images_frontend_before_show_variation` and `wc_additional_variation_images_frontend_init`, are not part of core. If a child theme still binds those, the new gallery looks like it does nothing.

Block themes need the current [Product Gallery block](https://woocommerce.com/document/product-gallery-block/), not Product Image Gallery, when the template also uses Add to Cart + Options. WooCommerce 11.1 warns in the sidebar if both sit together. The upgrade control replaces the classic block with default Product Gallery settings, so I restyle after the click. Official replies on the [color swatches roadmap](https://developer.woocommerce.com/2026/06/03/introducing-color-swatches-in-woocommerce-core/) are blunt: swatches live on Add to Cart + Options (Beta), and that block only syncs with the new Product Gallery.

Migration from the extension is an Action Scheduler job in `woocommerce-db-updates`. It copies `_wc_additional_variation_images` into `_product_image_gallery` in batches of 250 variations and requeues until empty. It is idempotent and will not overwrite a variation that already has a native gallery. Legacy meta stays on disk but is not kept in sync. CSV must match the live implementation: `meta:_wc_additional_variation_images` was the extension column, `meta:_product_image_gallery` is native. I export one hand-built variation first.

Parent products still need their own product image or product gallery. Clearing the variation is supposed to bring the parent set back. If the parent is a blank placeholder and every photo lives only on the children, reset looks broken. YouTube and Vimeo embeds are not the 11.1 video beta. That beta only plays uploaded files.

![Shopping bags on a counter used while testing WooCommerce variation galleries](../../images/blog/woocommerce-variation-galleries-2.jpg)

## Production checklist for variable product templates

A variation gallery is not done when the admin thumbnail looks pretty. Work this list on staging after the 11.1 database update.

1. Confirm WooCommerce is 11.1 or newer and database update `11.1.0-1` has run. The Variation gallery toggle should be gone from Settings, Advanced, Features.
2. Confirm Additional Variation Images is inactive. Reactivation should be refused after 5 September 2026.
3. On Status, Scheduled Actions, wait until `woocommerce-db-updates` is idle. Large catalogues need the 250-row batches to finish.
4. Edit one variable product. Set a parent gallery. On two variations, use Manage next to Variation gallery, order the photos, and confirm the first image is primary.
5. On a third variation, leave the gallery empty. Selecting it should not reuse the previous colour's extra shots.
6. Save on the Variations tab, then view the PDP logged out on a phone and a laptop, with cache bypassed.
7. On a block theme, put Product Gallery and Add to Cart + Options on the Single Product template. If the editor warns about Product Image Gallery, take the upgrade and restyle.
8. Enable Color swatches for attributes only after that template pairing is in place. The classic Add to Cart block will not show `wc-visual` swatches.
9. Keep the first visible gallery image eager. Format still follows [image formats that improve LCP](https://alanvo.com/blog/image-formats-improve-lcp/).
10. CSV imports use `meta:_product_image_gallery` with comma-separated attachment IDs, not the extension column.
11. Delete any gate on `wc_feature_woocommerce_additional_variation_images_enabled`. 11.1 removes the option.
12. If the theme overrides `single-product/add-to-cart/variable.php`, click every attribute combination.
13. Conflict-test with Storefront if a custom gallery plugin is in the stack, then put the real theme back.
14. Recheck zoom, pop-up, next and previous, and the empty-selection reset.

## What breaks on a live catalogue

What breaks on a live catalogue is a half-finished migration, leftover classic gallery markup, or custom code still writing extension meta.

The database update has not finished. Merchandisers added native galleries on hero SKUs while Action Scheduler was still copying. A later batch skipped those rows because native meta was no longer empty, and long-tail colours stayed on legacy keys the storefront no longer treats as source of truth. Custom code still writes `_wc_additional_variation_images`. The admin shows a gallery. REST `gallery_image_ids` stays empty because nobody called `set_gallery_image_ids()`.

A child theme still listens for Additional Variation Images JS events. `show_variation` fires. The slider never rebuilds. Switching to Storefront fixes it, which is the theme author's ticket.

![WordPress admin on a screen during WooCommerce variation galleries work](../../images/blog/woocommerce-variation-galleries-3.jpg)

The Single Product template kept Product Image Gallery next to Add to Cart + Options. The variation changes. The classic gallery stays on the parent photos. 11.1 warns in the editor. Ignoring that warning is how a lookbook PDP ships.

A variation with no gallery inherits the last colour's DOM because a custom slider never ran `reset_data`. CSV jobs keep the extension column, so production imports look rolled back overnight. Parent product has no image, so reset is a blank viewer. Two gallery plugins plus core bind zoom twice and wreck INP on the colour click.

## How I measure a gallery swap

I measure a gallery swap as a variation interaction that changes visible media, not as a Lighthouse score on a simple product.

In the field I watch INP on the colour or size control, CLS on the gallery box, and LCP for product URLs after the first swap. The LCP element should still be the viewer image, with width and height reserved so a four-image walnut set does not push add to cart. I look at `view_item` and add-to-cart on variable products in [GA4 ecommerce events](https://alanvo.com/blog/ga4-ecommerce-events/). If add-to-cart is fine and nobody ever selects a second image, merchandising paid for photos the template cannot show.

On staging I log `gallery_image_ids` in the variation JSON for oak, walnut, and a variation with no extra shots. I clear the selection and confirm parent HTML comes back. I crawl a sample of PDPs so the first image is in the initial HTML, not injected after a slider init. REST clients should round-trip `gallery_image_ids` without stuffing IDs into `image`.

I do not invent a conversion percentage for a gallery migration. Their Nibs published +31% conversions after a Shopify storefront rebuild. That figure is not a Woo gallery claim. Furniture and shoes still sell when the photo matches the SKU in the cart. That is the bar.

## Related work on this site

The [Skanvi furniture storefront](https://alanvo.com/work/skanvi/) is the brief: timber and fabric stories where a colour change has to swap a set, not a single hero. [Janet and Janet](https://alanvo.com/work/janet-janet/) is campaign footwear on a phone, where the size picker and the gallery share a narrow column. [Stitching Stories](https://alanvo.com/work/stitching-stories/) needs collection photography that still matches the PDP when a print colour is selected. All three were contract work on an agency team. WooCommerce variation galleries are how those catalogues stop depending on a retired plugin for a job core now owns.

![Product photography on a table for a WooCommerce PDP](../../images/blog/woocommerce-variation-galleries-4.jpg)

## FAQ

### Do I need WooCommerce variation galleries if each SKU only has one photo?

You do not need extra WooCommerce variation galleries if each variation honestly has one image. The primary image field is enough. Build the per-variation gallery when merchandising has more than one angle per colour or print, and when the PDP is supposed to show that set after the shopper picks the attribute.

### Will WooCommerce variation galleries work with a classic theme gallery?

WooCommerce variation galleries work with a classic theme gallery when that theme still uses the standard WooCommerce product gallery and listens to `show_variation` and `reset_data`. A theme that replaced the gallery with its own slider needs a compatibility pass. Test zoom, thumbnails, lightbox, and the clear-selection reset on Storefront first, then on the real theme.

### Can I keep Additional Variation Images next to WooCommerce variation galleries?

You cannot keep Additional Variation Images next to WooCommerce variation galleries on 11.1. Core deactivates the extension on upgrade and blocks reactivation because the functionality now lives in WooCommerce. Leave the legacy meta alone, finish the scheduled migration, and teach imports to write `meta:_product_image_gallery`.

### How do I import WooCommerce variation galleries from a CSV file?

Import WooCommerce variation galleries from a CSV file by putting comma-separated attachment IDs in `meta:_product_image_gallery` on each variation row, after the files already exist in the Media Library. Export one product you configured by hand and copy that column. Do not keep using `meta:_wc_additional_variation_images` on a native 11.1 store.


![Mobile checkout on a phone after WooCommerce variation galleries changes](../../images/blog/woocommerce-variation-galleries-5.jpg)


HTML version: https://alanvo.com/blog/woocommerce-variation-galleries/