Why WordPress 5.9 broke your galleries (and how to fix it)

WordPress 5.9 has introduced a whole load of pain for those of us using Gallery Blocks. The HTML code generated by WordPress changed. Without updates to your designs, your site could break.

What changed in WordPress 5.9?

Before 5.9 was released, galleries were presented in code as an unordered list of figures wrapped in a figure:

<figure class="wp-block-gallery">
  <ul class="blocks-gallery-grid">
    <li class="blocks-gallery-item">
      <figure>
        <-- IMAGE HERE -->
      </figure>
    </li>
    ...
  </ul>
</figure>

It’s been this way since before WordPress 5 and is used in countless themes by artists, photographers, fashion houses and so on. Basically anywhere a gallery appears.

WordPress 5.9 changed this structure. Galleries are now presented as nested figures without the list structure.

<figure class="wp-block-gallery has-nested-images">
  <figure class="wp-block-image">
    <!-- IMAGE HERE -->	
  </figure>
  ...
</figure>

The code looks simpler, although it has some profound impacts for both current and future galleries.

The grid has gone

If you’ve been using the list to structure and set your gallery’s layout you need a rethink. The outer container has gone, which could make it tricker to manage some aspects of your gallery design. It may also make your CSS more difficult to structure and manage.

Wp-block-image and image size classes now applies to images in the gallery

The wp-block-image class is used to style images throughout WordPress, with the size of image marked by size-* classes (e.g. size-full for a full sized image). These classes are now applied to the images in the gallery.

If the styling isn’t picked up in the CSS correctly, the images will present as if they were in the main flow of the page.

Design debt

My testing shows the new HTML only appears on galleries created or posts edited with 5.9. Your existing gallery code is preserved.

This means you’ll need to support both current and legacy code in your stylesheets, plugins, blocks and JavaScript. This is going to cause problems for sites with large numbers of historical galleries in the years to come.

However, over time it’s likely support for historical galleries will fade. A couple of years from now you might update your site design and inadvertently corrupt your pre-5.9 content.

Wp-block-gallery or has-nested-images?

With two different approaches to galleries working side-by-side, the WordPress “fix” is to add “has-nested-images” as a class to the figure container. You can use this to target new classes, but there’s no corresponding class for older galleries.

Updating existing pages

Untouched pages aren’t affected (for now) as they show the old HTML code. However, if you want to remove the old code and settle on a single design it is easy to do.

In your posts and pages views, select all the pages with “old” galleries. Choose “bulk edit” and then update. Bear in mind if you do this, the posts will have today’s date shown as when they were last changed. You also don’t know what else might break in your design, so check your galleries thoroughly.

Bottom Line

Buried in a release note, this “will break your design” change is a nuisance for those of us using galleries within our designs. It took about an hour for me to work out what had happened and redesign the CSS for the galleries to work with the new code. It will be longer if you’re also using Javascript.

Filed under:
Work: writing, research and design
#wordpress

My name is Ross Hori

I'm a freelance writer, designer and photographer. By day I create articles, features and reports. At night I take photos and write fiction. Find out more.

Follow Me: