Build a gallery in Gutenberg
Use the POM Gallery block to arrange library images in a grid, masonry layout, slider, carousel, thumbnail navigator or full-screen presentation. This guide is for content editors using the WordPress block editor with POM active.
Create and order a gallery
- Open Pages → All Pages or Posts → All Posts, then edit your content.
- Insert Gallery, choosing the POM block described as “Live media-library galleries with grid, masonry, carousel, thumbnails and full-screen layouts.”
- Select images from the media library.
- In Gallery images, choose Edit gallery images. Drag the thumbnails into the intended order and select Update gallery.
- Alternatively, use Move image earlier, Move image later and Remove image in the block settings.
- Save the page and preview it in a new tab.
The block stores attachment references and options, not copies of image metadata. Changes to alt text, title, caption, description, dimensions and responsive sources are reflected on the next uncached render. Clear page/CDN caches when checking a library change. Refresh library preview updates the editor preview without replacing the gallery.
Use meaningful alt text for informative images. Choose public image attachments; unavailable, private or trashed attachments are omitted. Import external images into the library before adding them. A gallery supports up to 500 image entries and 100 video entries.
Choose a layout
| Layout | Use and controls |
|---|---|
| Grid | Regular rows. Choose Columns, Mobile columns (below 768px), Image size and Item padding. |
| Masonry | Flow items into columns. Choose an uncropped image size when you want different image proportions. Column and mobile settings also apply. |
| Slider | One slide at a time, with optional fixed height or adaptive height. |
| Carousel | A horizontal strip with neighboring images visible. Set Image height (px) and optionally remove carousel gaps. |
| Image with thumbnails | A main slider and independently linked thumbnail navigation. Set its image height and navigation behavior. |
| Full screen | Image-only vertical slides filling the viewport height. Visitors can use vertical gestures or pagination. |
The column choices are 1, 2, 3, 4, 6 and 12. The default mobile setting uses one column below 576px and the main column count from 576px. An explicit mobile count applies below 768px. The main count applies from 768px.
Item padding uses the theme's rem helpers: 0, 0.375, 0.75, 1, 1.25, 2, 3, 4, 6 and 8rem. Space between adjacent images is twice the item padding. A rem follows the root font size.
Slider, carousel and thumbnail layouts offer arrows, dragging, looping, adaptive height, slide numbers and autoplay. Height is bounded to 1–4,000px and autoplay intervals to 1–10 seconds. Enable autoplay only when it helps visitors; verify that the gallery remains understandable without motion.
In Carousel, images always use Image height (px). Equal slide container heights additionally fixes the slide containers to that height, including video slides. In Slider, Fixed image height controls whether the fixed height is applied. Thumbnail layouts always use their configured height.
Edit gallery images is available in both the sidebar and floating block toolbar. Changing the layout retains the selection and hidden settings; only settings supported by the active layout affect its output.
Add overlays and lightbox actions
For Grid and Masonry, open Overlay:
- Choose Display overlay: None, On hover, Hide on hover or Always.
- Choose a solid background or bottom gradient, a theme palette color and opacity in 10% steps.
- Set alignment, frame, pointer-entry behavior and hover zoom as needed.
- Choose the title, caption, description, lightbox icon, linked title, link icon or button.
Overlay content comes from the media library. Destination links use the image's configured library destination. Buttons use the button styles configured in the theme.
In Click and lightbox, Open lightbox from the whole image takes priority over the whole-image destination link. The lightbox icon can remain enabled: it and the image cover open the same gallery item. Overlay destination links remain independent.
Show image description in lightbox uses the current library description. Slider, carousel and thumbnail images open the lightbox automatically. Full-screen mode uses its own vertical navigation instead.
Include videos
Open Videos after images, select Add video, and enter a YouTube or Vimeo URL. Choose an optional library thumbnail and aspect ratio. Use Move video earlier and Move video later to change their order. Videos appear after the ordered images. Full-screen mode is image-only; video settings are retained if you switch layouts but are not rendered in that mode.
The editor shows a poster or placeholder, not a playing third-party embed. Check playback on the frontend. Provider availability, privacy settings and any site consent requirements still apply.
Preview and verify
The editor reflects the theme's colors, image components and effective gallery styles. Preview overlay and the previous/next preview buttons let you inspect presentation without following links. The carousel preview shows an individual slide; frontend motion, the complete neighboring-slide arrangement, masonry packing and video playback must be checked in a new-tab preview.
Before publishing:
- Check the image order, alt text, crop and image quality.
- Review mobile, both tablet orientations, desktop and Very Large previews.
- Check arrows, thumbnail navigation, lightbox item counts and destination links.
- If using several galleries, verify that each thumbnail strip controls only its own main slider.
- Use Visibility to hide the entire gallery on selected devices; hidden blocks remain selectable in the editor.
- Use Advanced → HTML anchor only for a unique ID. Additional CSS classes accepts existing theme helpers.
Random order changes the frontend order on each uncached render, not on every visit to a cached page. The editor retains the saved order for predictable editing.
If the preview is empty, check the attachment status and video URL. If metadata or scripts appear outdated, refresh the library preview and clear the relevant page/browser caches. If an image is blurry, select a larger Image size rather than stretching a thumbnail.