Documentation
Docs

Gallery block

The Gallery block is an alternative to the WordPress core Gallery block.

The main advantage of the ska/gallery block is that it can render an image gallery with a simple and predictable markup: .wp-block-ska-gallery > .image > img. It is a singular block that renders images from a list of WordPress attachment IDs, as opposed to the core gallery block which contains individual image blocks as children – there are pros and cons to both.

When disabling the Wrap option, the gallery will not render any parent element, only .image > img elements. This makes it possible to use the Gallery block inside the Slider block for example, making each image a separate slide.

Basic gallery

Images: https://picsum.photos

You should give the gallery basic Tailwind classes such as grid grid-cols-2 sm:grid-cols-3 gap-3.5 to configure its’ appearance.

Gallery images can be targeted with the selector [&>.image] (or direct child selector: *). The .image is a wrapper element and contains the <img> element inside of it.

When enabling the “Cover” option the <img> elements automatically receive the Tailwind classes w-full h-full object-cover rounded-[inherit] aspect-[inherit], ensuring that all images fit their wrapper element rather than letterboxing. You can then give the .image elements a size (e.g. size-44) or an aspect ratio (e.g. aspect-square) or both.

The gallery images should have an alt-text assigned to them in the WordPress Media Library – alternatively you can change the “Role” option to “Presentation” to hide the images from screen readers.

Logos with individual links

Images: https://logoipsum.com

When changing the gallery block’s “Link to” option to “Custom links” you are presented with a textarea to which you can enter links for the gallery images. Each line corresponds to a gallery image in order. Optionally you can also add an aria-label to the link by appending the | character and writing the text after that. Links that start with @ are opened in a new tab.

Gallery “Custom links” option value example
https://google.com|Go to Google
https://bing.com|Visit Bing
@https://duckduckgo.com|Open DDG in a new tab

Synergies

Slider

The Gallery block can be used inside the Slider block, allowing the gallery images to become slides. In this case you should disable the “Wrap” option, otherwise the whole gallery is a single slide.

When a gallery is inside the slider, you shouldn’t add Tailwind classes the the Gallery block (as the wrapper won’t be rendered), but instead add them to the Slider block, targeting either swiper-slide (custom variant for [&_.swiper-slide]) or [&_.image], both of which target the same element – .swiper-slide.image. You can, how ever, still add Tailwind classes to the Gallery to control how it appears in the editor, e.g. grid grid-cols-auto-fit-xs gap-3.

Lightbox

The Lightbox block can contain any amount of Gallery blocks as well as other Image blocks to create a singular lightbox for all the contained images. When the gallery is inside the lightbox block, you should not enable the “Lightbox” option on the gallery, but instead simply change the “Link to” option to “Full Size” or some other image size that you wish to use for the lightbox.

Examples

When copy-pasting an example to your block editor, the Gallery images with the same ID-s may not exist, or be different images as in the examples – select the Gallery block and click on “Clear” on the block toolbar, and then add your own images to the gallery.

Image zoom on hover

Native horizontally scrollable gallery

First image col/row span

Grayscale, row-spanning first and last images

Masonry with multiple galleries

Note: works best with images that have different aspect ratios – remove the aspect-* classes from the galleries and use w-full h-auto instead.

Masonry with columns-n

Slider cards