Gallery plugins most often go wrong by putting a second gallery on the page, or by drawing images that only appear once a script has run. Three rules keep this plugin out of both.
Rule 1: one seam, and when it is gone the plugin stands aside
WooCommerce prints its gallery with the function woocommerce_show_product_images, hooked to woocommerce_before_single_product_summary at priority 20. On each product page the plugin:
- Waits for WordPress'
wpaction. Themes add and remove gallery callbacks during setup; deciding earlier would be deciding about a page that does not exist yet. - Checks whether your theme is a block theme whose Single Product template contains WooCommerce's gallery block —
woocommerce/product-image-galleryorwoocommerce/product-gallery— directly or inside a pattern the template uses. If so, it stands aside and records blocks. That block prints a gallery whatever is on the classic hook, so taking the hook over would give the page two galleries. A template written for one product (single-product-<slug>) is used in preference to the general one, as WooCommerce does. - Checks whether WooCommerce's gallery is still on its hook at priority 20. If your theme has removed it to draw its own, the plugin stands aside and records theme.
- Otherwise it removes WooCommerce's gallery and puts its own in the same place, so the gallery lands where your theme's layout expects it, and records ok.
The result is stored in an option (gmpgf_theme_status, or gmpg_theme_status in the full edition) and shown on the settings screen. It is only written when it changes, so a product page view is not a database write.
A block template built around WooCommerce's Classic Template block renders the classic page, so the plugin takes over there. A classic theme never has its template read at all.
Rule 2: the gallery works before the JavaScript does
Every image is a real <img> printed by the server, with your store's own srcset, at WooCommerce's registered image sizes (woocommerce_single for slides, woocommerce_gallery_thumbnail for thumbnails, full for the lightbox). The slides are laid out with CSS scroll-snap, so a shopper can swipe them before any script has loaded, and image regeneration, CDNs and lazy-loading keep working.
The first slide loads eagerly with fetchpriority="high" — it is the largest thing the shopper is waiting for. Every later slide is lazy-loaded.
The script then adds the arrows, keeps the thumbnails in step with the slides, opens the lightbox (closed with Escape), and lets the left and right arrow keys move between slides.
The gallery wrapper carries WooCommerce's own images class. A classic theme floats div.product div.images beside the product summary, so the gallery sits in your theme's two-column layout.
Rule 3: one list of images decides everything
The images a product shows are its product image followed by its product gallery images, with the product image left out of the gallery if it is repeated there. A product with no images shows WooCommerce's placeholder image rather than an empty box. Images deleted from the media library simply drop out.
The slides, the thumbnails and the lightbox all come from that one list, so they can never disagree.
What other plugins add to the gallery
WooCommerce's own gallery fires the woocommerce_product_thumbnails action inside it, and that is where other plugins add to the gallery — a product video (Gatemi Product Info's among them), a 360° viewer, a badge. Both editions fire that action inside their own gallery, so those items still appear. WooCommerce's own thumbnails callback, which this gallery replaces, is lifted off for the length of the call and put back afterwards, so core's thumbnails are never printed a second time.
Variations — Full edition
With Swap the images when a variation is chosen on, the gallery listens to WooCommerce's own variation events (found_variation and reset_data). The plugin never works out which variation is chosen; WooCommerce tells it.
For each variation the gallery shows:
- the variation's own Gallery images for this variation, when set — replacing the product's gallery entirely;
- otherwise, the variation's own image first and the product's gallery after it;
- otherwise, the product's gallery.
The images for every variation are printed into the page once, rather than fetched, so trying four colours is not four requests. A variation that would show the product's own images adds nothing to that data.
Variations — Free edition
The free edition does what WooCommerce's own gallery does: when a shopper chooses a variation that has its own image, that image takes the place of the first slide (and its thumbnail), and the product's image comes back when the choice is cleared. It uses the image WooCommerce hands over on found_variation and restores on reset_data; a variation with no image of its own leaves the product's images as they are. Separate image sets per variation are the full edition's.
Hover zoom — Full edition
With Magnify on hover on, each slide gets a zoom layer that loads the full-size image and magnifies it 2.5× under the mouse (change it with gmpg_zoom_level). It is applied only where the browser reports a fine pointer that can hover — never on a touchscreen.
