How it works
How the gallery replaces WooCommerce's product images, which images and sizes it uses, and how it handles variations, phones, keyboards, caches and languages.
Replacing the WooCommerce gallery
- Classic themes: the gallery takes the place of WooCommerce's product images on single product pages, and WooCommerce's own zoom, lightbox and slider are switched off.
- Block themes: the Product Image Gallery block in the single product template is replaced, keeping the sale badge.
- Not replaced automatically: WooCommerce's newer Product Gallery block, and page builders or themes with their own image widgets. Use the shortcode there.
- The gallery keeps WooCommerce's
imageswrapper class, so it sits beside the product summary in the usual two-column layout. - Turn Enable Product Gallery off (General) to bring WooCommerce's default gallery back.
Images and sizes
- Order: the product image first, then the gallery images. An image used twice is shown once.
- Main image: WooCommerce's single product size, with responsive
srcset. Thumbnails: the gallery thumbnail size. Zoom and lightbox: the full-size original, loaded only when needed. - Alt text comes from each image, or the product name.
- A product with one image shows no arrows or thumbnails; zoom and the lightbox still work. A product without images shows WooCommerce's placeholder, without a lightbox.
Navigating
- Click a thumbnail or an arrow, or swipe the main image on touch screens. The image changes with the Transition you chose, and navigation loops from the last image to the first.
- When there are more thumbnails than fit, drag the strip with the mouse, swipe it, or use its scroll buttons.
- With focus in the thumbnail strip, ← → move between images.
- Clicking (or pressing Enter on) the main image opens the lightbox when it's enabled. With Inner Zoom on a touch screen, a tap zooms instead.
Variable products
- Choosing a variation shows its image: if it's already in the gallery the slider moves to it; otherwise it replaces the first image.
- Clearing the selection restores the first image.
- Variation galleries (several images per variation, WooCommerce 10.8+) aren't supported and can replace the gallery with WooCommerce's default.
Performance
Styles and scripts load only on single product pages while Enable Product Gallery is on, with no jQuery dependency (plus WordPress's Dashicons font for the icons). Your settings are printed as a few CSS variables, with no extra request. The first image loads immediately; other slides and thumbnails load lazily, and full-size images only when the lightbox or zoom needs them.
Accessibility
- Every control is a labelled button ("Previous image", "Show image 3", "View full-size image").
- The lightbox is a modal dialog: focus moves in, stays in while open and returns on close; the counter is announced.
- Visible focus rings, and no animations for visitors who prefer reduced motion.
Caching & languages
- Settings are printed into each product page, so purge your page cache after changing them.
- Translation-ready. With WPML or Polylang, the shortcode's
idfollows the visitor's language. - Right-to-left sites work; arrow and swipe directions stay left-to-right.