WooCommerce Core

Adding support for WooCommerce 3.0’s new gallery feature to your theme

As you know we’ve redesigned the product gallery feature in WooCommerce to deliver a richer experience in 3.0.

This is a significant frontend change that can be broken down in to three separate new features;

  • Image zoom / magnification
  • Lightbox
  • Slider

To enable each of these features in your theme you must declare support using add_theme_support() like so;

add_action( 'after_setup_theme', 'yourtheme_setup' );

function yourtheme_setup() {
    add_theme_support( 'wc-product-gallery-zoom' );
    add_theme_support( 'wc-product-gallery-lightbox' );
    add_theme_support( 'wc-product-gallery-slider' );

This allows you the flexibility to pick and choose exactly which features you want to include/exclude in your theme or at your store.


If your theme disables WooCommerce core styles you will also need to provide a layout for the new gallery. The classes you’ll want to work with are;

  • .woocommerce-product-gallery – The gallery wrapper. This wrapper will also include a class that indicates how many columns thumbnails should be arranged into, e.g. .woocommerce-product-gallery--columns-4
    • .woocommerce-product-gallery__wrapper – The slider wrapper
      • .woocommerce-product-gallery__image – The figure that contains the image itself, which is wrapped in an anchor
  • .woocommerce-product-gallery__trigger – This is the link that triggers the lightbox functionality
  • .flex-control-thumbs – If you’re using the slider functionality the Flexslider script creates the thumbnails in a ol with this class

A note on the column class; If you anticipate that your users might want to change the columns using the woocommerce_product_thumbnails_columns filter, you might also want to include styles for other column layouts besides the default.

If you’re interested you can find the sass we use in Storefront to style the new gallery layout here.

That’s it! Go forth and add support for WooCommerce 3.0’s gallery feature to your themes!

By James Koster

Product Designer

43 replies on “Adding support for WooCommerce 3.0’s new gallery feature to your theme”

I was testing a new product gallery update (RC1 3.0.0) in Twenty Sixteen as well as Twenty Seventeen. For the variable products, I have noticed that when I select the product variation, the first picture in thumbnail gallery displays in it’s original size i.e larger then the all remaining thumbnail gallery pictures. While testing in storefront theme it works good, no resized thumbnail.

Liked by 1 person

@Chirag Did you post this on github? I’m having the same issue so I can +1.

@James Koster currently the new gallery features work great after adding theme support for it in my custom theme. However, it only works on single product pages but not on product pages shown on other pages through shortcode [product_page id=”99″] , is this intentional or will this be added in an update?


You’re right James, I was quick to jump to conclusions, the shortcode is working fine inside the standard content field. However, this particular shortcode is displayed inside a container generated through advanced custom fields plugin and then displayed using add_filter( ‘the_content’,…). It seems like the photoswipe and zoom css and js are not getting called… I’m testing where the problem is and will report back when/if I find it (might just be some bad coding on my part).

please delete above comment


The new gallery code scans the post content for [product_page… shortcode, but since my added content containing the shortcode was added to the post content through add_filter( ‘the_content’,…) , the scan doesn’t find the shortcode and doesn’t call the new gallery scripts and css. I managed to fix this by including the shortcode [product_page] in the main content field. This doesn’t actually show any product but does trigger the call to the new gallery scripts and css.


Hi James,

Thanks for the reply. But in this post they don’t explain where to put the code. They just say “add this code”. Since i’m not a theme builder i have no idea where to add these codes.

Kind regards,

Liked by 1 person

Can you clarify that the code above needs to be edited – that is, my child theme is called “Dynamik.” So would I change:

add_action( ‘after_setup_theme’, ‘yourtheme_setup’ );

function yourtheme_setup() {
add_theme_support( ‘wc-product-gallery-zoom’ );
add_theme_support( ‘wc-product-gallery-lightbox’ );
add_theme_support( ‘wc-product-gallery-slider’ );

to read:

add_action( ‘after_setup_theme’, ‘dynamik_setup’ );

function dynamik_setup() {
add_theme_support( ‘wc-product-gallery-zoom’ );
add_theme_support( ‘wc-product-gallery-lightbox’ );
add_theme_support( ‘wc-product-gallery-slider’ );

? Or do I also replace the word “theme” where still visible above with Dynamik? Thanks for any tips!


That can work, but if this is a WC theme you may want to ask the author to include it. You may also want to choose something more unique than ‘dynamik_setup’ in case they do the same! Any name/prefix will work.


I’m currently using the Divi theme and it looks like they have chosen the product zoom by default without the ability to switch back to lightbox. A bad move to force a site to change functionality.

How can I turn off the zoom feature and revert back to lightbox using functions?


But just to clarify.

The implementation of one of the three image gallery methods (lightbox, zoom or slider) is a choice made by the theme developer?



This works perfectly. Thank you so much.

Is there an option to have image caption or title from image metadata, displayed across main image when clicked on thumbnail or how to achieve that.

Other option is to have caption showed on thumbnails if it is easier to achieve.

Thank you so much.

Best regards.

Liked by 2 people

Is there a simple way, using Woo Canvas to switch off the zoom facility – or does this need to be coded in functions.php in the child theme?


Artificer theme, one of the free ones from WooCommerce has an update to 1.3.17 to integrate WC version 3 changes, but I’m stuck on 1.3.16 in my WordPress. I’m not getting the option to update my theme within WordPress and am not tech savvy enough to want to do this manually. I have a bunch of friends in the same situation.
How can I get WordPress to recognise that there is a theme update due and apply it to my site? The products won’t display properly following the WC3.0 update, so I need the theme update too.


I found the WooCommerce Helper plugin which has updated the theme file, but sadly it still is not working properly with the new WC version 3+.


Artificer theme is broken by the update. Even though there is a new theme update, the new theme doesn’t work either. The front page featured products will not display. It must be affecting thousands of people who use the free Artificer theme for their Woo Stores. I can’t find how to fix it.


Hi James. My bloggy pals and I have all now got the latest everything, including the new Artificer release 1.3.18 which is supposed to fix the featured product images issue. However none of us can still get featured products to show on the front page of our stores. Couple of examples here – and We’re all in the same position. It all worked before, now it won’t work for any of us despite the new theme update.
“2017.05.12 – version 1.3.18
* Fix – Fixes the WooCommerce 3.0.0 compatibility for the featured products query.”
We don’t know how to fix this 😦 Can you point us to any help docs that might sort this problem out?

Liked by 1 person

Edit to my last comment. The new theme is working for sites where they already have featured products in place before the WC 3.0 update – see this example. However for more recent sites set up that didn’t already have featured products before the update, they can’t get the featured products even with the 1.3.18 theme update. Hope that helps you track down the problem and solve it for us all soon 🙂 Thank you so much.


Comments are closed.