Refactoring Gutenberg’s Gallery Block To Support Nested Images

Like many others, I often have pinned tabs of all sorts of things in my browser. Some of them linger there for months. Others for years, I shamefully admit. Of the handful of Gutenberg-related browser tabs I have had pinned since late 2020, one of them finally had the sort of movement I have been waiting on. The Gallery block was finally getting the much-needed refactor it needed.

A gallery is essentially a container with nested images. The concept of nested blocks has existed and has been in use for a long while now. However, the core Gallery block does not make use of this capability. This means that users have no access to existing Image block features.

Want to customize the link for individual images? No can do with the Gallery block. Instead, users must use Columns and drop Image blocks in. It is such a fundamentally broken part of the user experience there is little wonder that users have looked outside of core WordPress for alternative solutions. And it has been a problem since the introduction of galleries via the shortcode system in WordPress 2.5.

Want to alternate styles for each image in the gallery? That has traditionally been impossible too. However, when each image is an Image block, users can alternate between square and round styles, for example.

Gallery block in the WordPress editor with alternating round and square image shapes.
Alternating Image block styles in a Gallery.

Users can even use a plugin like Editor Plus with its extended Image block styles to create a Gallery of “image blobs” or animate them individually.

Gallery of images with "blob" shapes.
Individual images with “blob” shapes via Editor Plus.

This change could open some layout possibilities where users control the positioning of each item in the grid. And, why stop with images? There is no reason that core could not open the block up to other types of nesting in the future, such as videos, quotes, and more.

Image gallery with a quote as one of the grid items.
Gallery of images with a quote.

The downside to this new feature is that it could require more work from developers who have already built on top of the Gallery block. That is why it is fundamental that they test this change now.

Testers can see the change by switching to the gallery refactor branch via GitHub or grab a ZIP file of the build. It adds a new “Gallery Refactor” option to Gutenberg’s Experimental setting screen, which must be enabled.

Only newly-added Gallery blocks will use the new format. Nothing changed about it at first glance. However, by selecting an individual image, users can use the typical Image block settings. The two exceptions are the align and resize options, removed because they would break the layout. New galleries also do not work in the site editor yet.

“While the expectation is nothing changes in terms of output, this is a pretty major change on a technical level for a very popular block, so it’d be a huge help to gather as much testing feedback as possible,” wrote Glen Davies in the announcement post.

This statement could be misleading. There are fundamental, backward-incompatible changes to the markup output with the new implementation.

In previous iterations of the gallery, it had a wrapper container (<div>) and an unordered list (<ul>) of images. The proposed change would remove the list entirely, dropping the Image blocks as direct children of the containing element. This will break custom theme styles and potentially plugin integration.

On a technical level, I do not see the need to change the outer markup galleries. It is only the image part of the equation that needs to change. If this is because of limitations with the InnerBlocks system (nested blocks feature), perhaps it is not robust enough to meet developers’ needs.

With continual breaking changes to markup and CSS in the core block system, coding the entirety of a site’s CSS from scratch is probably a thing of the past. This is not the first instance of such breakage and will undoubtedly be the last, a rarity in the pre-block era. The best course of action is for theme authors to leave core styles in place and extend them, even if it means some bloat for page loads. It is not a fool-proof plan, but it lightens the burden.

Overall, I welcome the Gallery block enhancement, even it breaks a few things. It potentially opens a world of possibilities and is necessary if the project ever wants to provide end-users with anything other than super basic functionality.


9 responses to “Refactoring Gutenberg’s Gallery Block To Support Nested Images”

  1. The more I hear about blocks, the less I like them. Newbie user, not developer, and my work is with small, volunteer organizations’ sites, so not a commercially important reaction.

    Just a question—what is wrong with using columns of individual images? It seems very understandable, columns keep the images properly lined up, and presumably the images could be whatever shape one wants? Why must there be a single gallery holding them all, why not just have the ability to group them into a unit, as one does on a print-layout page if one wants to move them together?

    • From a technical standpoint, columns and galleries are not the same thing. I would describe them both as different subsets of layout grids, each with their own pros and cons. Columns don’t have rows, for example. You could fake them with the Columns block, but you couldn’t do things like equal-height image cropping with it, automatically switching all the image sizes at once, or just any bulk operations on all the images in the group at once.

      And, there is certainly nothing wrong with a user building out a custom image layout via the Columns block. However, it’s simply easier to get images loaded up and laid out automatically with the Gallery block.

      I could also potentially see some accessibility concerns. Or, at least there are semantic markup issues using Columns if you are, in fact, building a gallery — in my mind, that automatically creates accessibility issues. The end result might look OK, but the under-the-hood stuff would be problematic.

      From the user experience end of things, I would think the average user would jump to using the Gallery block before the Columns block to create an image gallery. It might not be until later (after adding their images) that they realize there are some missing features. So, it makes sense to round out the feature set of the Gallery block, which is the common starting point.

    • I’ve seen the ticket. The first reply was asking for additional feedback. But, the OP never answered what were legitimate questions. Having a different opinion doesn’t mean that you’re not open.

      Admittedly, I thought it was closed prematurely after a week, but the person closing also said they were happy to reopen with more insight.

      Sending out feature requests is fine. However, you need to back up your arguments for inclusion of something new or changes to features. Basically saying, “I want this,” is not always good enough to give a request the green light.

      What changed? Someone put in the time and effort to make it happen.

  2. As a Gutenberg fan, I welcome such improvements, even if it means I have to refactor some custom code. Mostly it’s for the better, and how many popular page builders are held back and unable to utilize modern techniques as css grid or custom properties due to backwards compatibility? It’s not much fun.

    But forgive me for the maybe stupid question. But could Gutenberg not just let the old gallery block be as is, and create a new “modern gallery” block, maybe offering that as default when inserting? It can’t be that much legacy code. Out of date blocks could even be moved to a plugin during transition? Like the classic editor? I could do without the spacer block – that’s for sure. :)

  3. Thanks for writeup!

    “While the expectation is nothing changes in terms of output … This statement could be misleading

    Thanks also for pointing this out. The “nothing changes in terms of output” was in terms of what the end user sees, but I can see how most people reading this post would be thinking in terms of html output, so I will try and get that post updated with something like the following, which also explains the reason for the underlying markup change.

    “While the expectation is nothing changes in terms of output for the end user, this is a pretty major change on a technical level for a very popular block, including a change in the underlying markup to align it with the W3C WAI guidelines on grouping of images (, so it’d be a huge help to gather as much testing feedback as possible.”


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: