Develop WooCommerce

The official WooCommerce development blog

WooCommerce Blocks 1.4.0 Release Notes — February 13, 2019

WooCommerce Blocks 1.4.0 Release Notes

Version 1.4.0 of WooCommerce Blocks is now available as a feature plugin. It’s the easiest, most flexible way to display your products on posts and pages!

What’s new in 1.4.0

Products by Attribute Block

Screen capture of adding the Products by Attribute block, selecting an attribute "Color", then selecting "Blue". After clicking Done, the preview shows a grid of products.

As the name suggests, this block will display any products that have been assigned a specific attribute term, or multiple attribute terms. If you’ve tried the Products by Category block, the UI should feel familiar.

Aside from the attribute selection options, the settings match our other product grid blocks. You can arrange the layout into a specific number of rows and columns, and you can order the products by a variety of options like newness, price, rating, sales, etc.

Featured Product Height

It’s now possible to specify a custom height to the Featured Product block. It works by adding a handle to the bottom of the block, which you can drag to make the block taller.

Screen capture of dragging the handle to grow the block.

Featured Product background image

In addition to setting a custom height, you can now also set a custom background image for the Featured Product block.

screenshot of the block toolbar, with the "Edit Media" button in focus.

Lots of bug fixes

That’s it for new features, but 1.4.0 also includes a bunch of handy fixes and improvements:

  • The correct product image placeholder is now displayed in previews.
  • It’s no longer possible to create broken layouts by displaying products in grids with too many columns.
  • Adding a Featured Product block without an image will not cause a PHP notice.

1.4.0 Changelog

The full changelog for 1.4.0:

  • Feature: Added new block: “Products by Attribute”
  • Enhancement: Added the ability to resize the Featured Product block (a default and minimum height can be set by your theme)
  • Enhancement: Updated button on Featured Product block to match core button block behavior
  • Components: Added new control component GridLayoutControl to manage row/column layout values
  • Components: Updated ProductAttributeControl to list only attribute types, then once selected, list terms in that attribute
  • UX: Remove ability to change selected product in Featured Product block, to prevent “sticky” product links.
  • Fix: A product without an image will now use the placeholder image in grid-layout block previews
  • Fix: Previously, there was a PHP notice when a Featured Product has no background image
  • Fix: There is now an enforced limit on column and row counts (which can be set by your theme)
  • API: Added attr_operator support to products endpoint to compare product attribute terms
  • Build: Update packages
  • Build: Remove unnecessary internationalization build step

What’s next?

We’re aiming to merge this feature plugin in to WooCommerce core for 3.6. Before that happens we anticipate one more major release for WooCommerce Blocks. A few new features are planned for that release such as block transformations, and enhanced customisability.

Using the WooCommerce Blocks plugin

To get started with WooCommerce Blocks, make sure you are updated to the latest version of Gutenberg, or running WordPress 5.0.x. Then download the latest version of the plugin here or venture over to Dashboard → Updates, to update the plugin from from WordPress.

As always, if you have feature requests, or spot any bugs,  please log them in detail on Github.

Adding support for WooCommerce 3.0’s new gallery feature to your theme — February 28, 2017

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!

New product gallery merged in to core for 2.7 — October 19, 2016

New product gallery merged in to core for 2.7

Followers of this blog will know that we’ve been talking about the possibility of revamping our product gallery display on single product pages. This post is simply to document that this has now been confirmed and indeed merged in to core. The feature will be included in WooCommerce 2.7.

Here’s a (very) quick video demonstrating the new gallery:

The improvements, in a nutshell

To re-iterate the points from previous posts;

  • Visitors now have access to both magnification and zooming (lightbox)
  • Gallery behaviour is more intuitive – clicking a thumbnail updates the main image rather than opening a lightbox
  • Dramatic improvements on handheld, in particular; touch gestures – swipe to scroll through the gallery, pinch to zoom, swipe up to close, etc
  • Opening the lightbox on mobile now displays the image in it’s true size, larger than the in-page display 🎉

Theme and plugin authors, please heed the following message

If you develop a WooCommerce theme or plugin that interacts with our gallery in any way we highly recommend that you checkout the WooCommerce master branch and test your product against it as soon as you possibly can. Themes will very likely need a few CSS updates to support the new gallery. Things to look out for include;

  • We’ve adjusted how thumbnail columns are laid out. No more first and last classes, just a single .woocommerce-product-gallery--columns-x class applied to the gallery wrapper.
  • When working on integrations with default themes we noticed some button style conflicts with the buttons in Photoswipe (lightbox).
  • You’ll need to style the Photoswipe trigger (.woocommerce-product-gallery__trigger)

Beyond this, we hope the update will be fairly unobtrusive. But we must stress that this is a potentially breaking change so it’s always best to test these things sooner rather than later.

Your thoughts welcome

2.7 is still a ways off, so if you spot any bugs, or don’t like something we’ve done with the gallery then now is the time to make your voice heard. As always, github is the place to do so.

The New WooCommerce Product Image Gallery — September 7, 2016

The New WooCommerce Product Image Gallery

A couple of weeks ago we posted about an experiment we were working on to improve the product galleries in WooCommerce, particularly the mobile experience.

We laid out options to have a lightbox, a magnification/zoom, or both and included a poll to get your feedback. After 442 votes, the results of that poll look like this;

  • Lightbox – 18.55%
  • Zoom/Magnification – 51.81%
  • Both – 29.64%

What do these results show us?

  1. The majority of folks (81.45% – ‘both’ voters + ‘zoom’ voters) like the zoom/magnification feature
  2. A significant number of people (48.19% – ‘lightbox’ voters + ‘both’ voters) feel that we need to continue including a lightbox

Based on these results and internal discussions we’ve decided to include both a lightbox and a zoom/magnifier. To do this we’ll use the popular Photoswipe script for lightbox functionality alongside our own Flexslider which handles the carousel/swiping on mobile. Zoom is our script of choice for zooming.

How does it look

A little something like this;


And on mobile;


The (extra) nice thing about the mobile experience (which isn’t possible to capture in a desktop browser), is that you can tap/pinch to zoom once the lightbox is open which makes it feel very ‘native’. You also get to see the full size image, regardless of what size your thumbails display at.

Can I play with it?

You sure can. Just check out the add/product-galleries branch on github. There are a few styling tweaks to work through, and variation images don’t work yet. But you’ll get a very good idea of how things work.

Once again, a note to theme authors

Shamelessly copy/pasted from the previous post;

This change involves template changes to templates/single-product/product-image.phpand templates/single-product/product-thumbnails.php as well as the addition of some new scripts and a little css. If you dequeue WooCommerce styles in your theme and roll your own, you’ll need to add some css to support the new gallery.

Let us know what you think! 🙂

A new product gallery coming to 2.7. Maybe. — August 18, 2016

A new product gallery coming to 2.7. Maybe.

The product image galleries in WooCommerce basically haven’t changed since version 1. The layout is fine, but the lightbox functionality is looking more than a little tired.

Most importantly the experience on smaller handheld devices is terrible. We’d like to replace the lightbox functionality entirely with a carousel/zoom combination which will provide a lightweight, intuitive experience for both desktop and handheld devices.


Just so we’re on the same page as to exactly how terrible our current implementation is for small screens check this out;

That’s right, the image that appears in the lightbox is actually smaller than the image displayed in the page itself.

Of course we could just disable the lightbox for small screens, but without a carousel it wouldn’t be possible to see the additional images at a size any larger than the small thumbnails. We need another solution.

How do we propose to address this?

I think we can agree that the lightbox is pointless on small screens. What works very nicely is a carousel with touch support to easily swipe between images. Something like this:


I don’t expect many WooCommerce users to be opposed to this change. What I’d really like you to consider is how our galleries behave on desktop.


We’ve agreed that a carousel is better for mobile. I happen to like the carousel for navigating the gallery on desktop as well. We’re already loading the script for mobile so it makes sense to use it on desktop too.

The question then becomes; How do we provide the ability to see the image in greater detail? There are a couple of potential answers to that question each with it’s own pros/cons.


The pros of using a lightbox are that it is familiar. It’s what we have currently.

But that’s about it.

The cons are several

  • Lightbox scripts are fairly hefty and include a lot of functionality that we don’t really need
  • Generally require additional assets (css) on top of the js
  • Given we’ve agreed that a carousel is the way to go for gallery navigation, it’s somewhat counter intuitive to have that method of navigation in addition to lightbox gallery navigation


Zooming in on the main product image as you hover over it is an alternative option. Here’s how that would look;


The pros

  • It provides a very intuitive overall experience. You click the thumbnail you want to look at then simply hover over the main image for more detail.
  • It’s lightweight. Including CSS, PrettyPhoto (our current lightbox script) weighs in at 30kb. The zoom script is 6kb. That’s an 80% decrease!
  • It’s consistent – the desktop / mobile experience mirror one another.

The cons

  • This solution is dependent on the theme to display the product image at a reasonable size. If the image is tiny, zooming might feel a little awkward.
  • It’s different. Not sure this is necessarily a con but it’s a very important to consider for store owners. Changes like this do have the potential for disruption.


I really wouldn’t want to do this, but it is of course an option to have zooming and a lightbox.

Over to you

What do you think? We’re very keen to hear feedback on this idea, in particular on the desktop behaviour.

If you’d like to actually test this functionality please check out the add-product-galleries branch on github. It goes without saying that you should only do this in a development environment.

Please vote in the poll!

A note to theme authors

This change involves template changes to templates/single-product/product-image.php and templates/single-product/product-thumbnails.php as well as the addition of two new scripts and a little css. If you dequeue WooCommerce styles in your theme and roll your own, you’d need to add some css to support the new gallery.