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;

[code language=”php”]
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!

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

  1. […] Adding support for WooCommerce 2.7’s new gallery feature to your theme […]

  2. […] Adding support for WooCommerce new gallery feature to your theme […]

  3. 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.

    1. Best to open this as an issue on github.

    2. @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?

      1. Hmm it should work, I just tested myself and can’t see any issues. I suggest posting in support and opening a github issue if you think you’ve found a bug.

        1. 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

        2. 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.

      2. @woutcompay Well I have edited css classes. It seems working fine for me.

  4. Is there to be update to WooThemes for the alteration to product display?

  5. My product info is totally messed up due to the update of Woocommerce. Where do I add the code mentioned above so my store looks like it should agian?! I think the .woocommerce-product-gallery–columns-4
    should do the trick right?

    thanks for the help!

      1. 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,

        1. Which code in particular? You may want to speak to your theme author, or use a WooCommerce specific theme.

          1. the theme is suppost to be Woocommerce specific but i will check with the theme author.

          2. Perhaps they didn’t test with 3.0 yet? Have you checked for an update?

        2. cvasoya Avatar

          Use that code in your functions.php file

          1. thanks for the help everyone! There is no update for the theme yet but i’m hoping it will come soon.

          2. Hai, i have got the same problem. Where can i find the functions.php file? I use woocommerce in the Shop Isle theme but it seems i’ve lost the editor as well..

  6. hollyknott Avatar

    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!

    1. 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.

  7. Hi folks,

    I have this to work with my custom theme (local dev MAMP) but I want it to have directional arrow links and want the images below the main slider image to be like this example.

    How do I go about doing this in my custom theme? I am totally lost.



    1. Hey Mike, you answered my question on Stackoverflow and directed me here but I need some help if you have time. I basically want my single product images to look like this:

      This is how it looks now:

      but I want it to be like the flex slider example

      If you could help I would be very grateful.



      1. You can filter the flexslider parameters here

        You’ll need some CSS tweaks to copy the flexslider demo 100% though.

      1. Hi James,

        Thanks for both of the replies. I will check out the links and do some digging,

        Have a great day,


  8. 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?

    1. Hard to say without seeing their implementation. Probably best to contact them about it.

      1. 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?

  9. vvnenovv Avatar


    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.

  10. gcwebbyuk Avatar

    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?

    1. You’ll need to add this as a customisation.

  11. balvan64 Avatar

    The new Slider does not work in an RTL site, the pictures (.woocommerce-product-gallery__image) slide to the wrong side.

    1. Please open an issue on github 🙂

  12. Deby Coles Avatar
    Deby Coles

    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.

    1. Deby Coles Avatar
      Deby Coles

      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+.

  13. Deby Coles Avatar
    Deby Coles

    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.

    1. We’ll look into this. Expect a release soon 🙂

      1. Deby Coles Avatar
        Deby Coles

        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?

        1. Deby Coles Avatar
          Deby Coles

          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.

        2. Hi Deby

          Have you by any chance open up a support issue for this? If you haven’t could you please do that so I can take a look at your case. Please mention in the ticket that @jeffikus told you to log it so that the support staff can allocate it to me.

          Submit a ticket here ->

          Thanks so much!

          1. Deby Coles Avatar
            Deby Coles

            Thank you, I will do that now.

Leave a Reply

Your email address will not be published. Required fields are marked *