Repository navigation
Gallery Layouts
PhotoPress adds three layouts to the core Gallery block: Masonry, Rows and Mosaic. You choose them in the block editor, from the inserter or from the PhotoPress panel in the Gallery block's sidebar.
- WordPress 6.6 or later.
- The block editor. The layouts are settings of the core Gallery block (
core/gallery). - Block themes and classic themes both work. PhotoPress applies the layout when the block renders.
- Masonry and Mosaic need JavaScript in the visitor's browser for their final layout. Rows is CSS only.
Open PhotoPress › Settings and choose the Gallery tab. Each switch saves when you change it.
The Gallery tab, with a switch for each layout.
| Control | What it does | Default |
|---|---|---|
| Masonry layout | Offers the Masonry layout for the Gallery block in the editor. | On |
| Rows layout | Offers the Rows layout for the Gallery block in the editor. | On |
| Mosaic layout | Offers the Mosaic layout for the Gallery block in the editor. | On |
A layout you turn off is no longer offered for new galleries. Galleries that already use it keep it, and its name stays in their Layout list.
- Open the block inserter.
- Search for "Masonry Gallery", "Rows Gallery" or "Mosaic Gallery", or type "photopress".
- Insert the block and add images as you would to any Gallery block.
The Masonry, Rows and Mosaic Gallery variations in the block inserter.
The three entries are block variations of the core Gallery block, not separate blocks. They also appear in the block's variation switcher, with a Gallery entry that returns a gallery to core's columns.
Select a Gallery block and open the PhotoPress panel in the block sidebar.
The PhotoPress panel of a Gallery block in the Masonry layout.
| Control | What it does | Default |
|---|---|---|
| Layout | Default (columns), Masonry, Rows or Mosaic. Lists the layouts turned on in the Gallery tab, and the gallery's own layout if it was turned off later. | Default (columns) |
| Column width | Masonry only. The width of each column, 100–800 px. | 300 |
| Row height | Rows and Mosaic only. The height of each row, 100–800 px. | 300 |
| Slideshow | Opens the Full-Screen Slideshow when an image is clicked. Works with any layout, including Default (columns). | Off |
| Hide captions | Keeps the image captions in the content but does not show them in the gallery. The gallery's own caption still shows, as does a Taxonomy Gallery's File name and title. Works with any layout. | Off |
The gallery's spacing (block gap) sets the space between images in every layout.
Columns is hidden
While a gallery in a PhotoPress layout is selected, PhotoPress hides core's Columns control in the sidebar. The layouts set their own columns or rows, and Columns has no effect on them. Columns shows again when you choose Default (columns).
The same layout code runs in the editor canvas.
Masonry: fixed-width columns, each image at its own height.
- Columns are the Column width wide, or the gallery's width when that is narrower.
- As many columns fit as the gallery's width allows. The columns are centered in the gallery.
- Each image goes at the foot of the shortest column, the leftmost of equal columns.
- Images keep their natural height. Core's Crop images to fit has no effect.
- The gallery caption sits below the columns.
Rows: each image at the row height and its own width.
- Each image is shown at the Row height and its own width.
- Images wrap to a new row when the next one does not fit, so a row can end short of the gallery's edge.
- An image too wide for the gallery at the row height is scaled down to the gallery's width. It is not cropped.
Mosaic: rows that fill the gallery's width.
- Images are added to a row until, at the Row height, they reach the gallery's width.
- The row's height is then adjusted so its images fill the width exactly at their own proportions.
- A last row that is not full stays at the Row height and does not stretch across the gallery.
- Each image's shape comes from the attachment's stored width and height. The editor uses the same values, so the editor and the page lay out the same rows.
The editor canvas runs the same layout code as the front end. Masonry and Mosaic lay out again as images load, as you add, remove or reorder images, and as the canvas width changes.
- Masonry and Mosaic are laid out by a short script printed inline right after each gallery. The browser first paints the gallery already laid out, so images do not move when the page's scripts run.
- Until that script has run, the gallery is hidden. It is shown after 3 seconds in any case.
- A second script,
dist/gallery-layouts.build.js, loads in the footer on pages with a Masonry or Mosaic gallery. It lays each gallery out again and keeps it laid out when its width changes, for example when the window is resized or a phone is turned. Masonry also lays out again as images without width and height attributes load. -
Rows loads no script. Each image with a
srcsetgets its width from its shape times the row height in CSS, so the rows are laid out the same before and after the image files arrive. - Without JavaScript, Masonry images stack in one column of the column width, and Mosaic rows are filled by CSS alone, which crops images to fit.
PhotoPress sets each image's sizes attribute to the widest the image is shown in its layout, so the browser picks a file of the right width from srcset.
| Layout | sizes |
Width W |
|---|---|---|
| Masonry | (max-width: Wpx) 100vw, Wpx |
Column width |
| Rows | (max-width: Wpx) 100vw, Wpx |
image width ÷ height × Row height, rounded up |
| Mosaic | (max-width: Wpx) 100vw, Wpx |
image width ÷ height × Row height, rounded up |
An image of unknown shape is taken as square. WordPress keeps this value when it adds srcset. For a lazy-loaded image WordPress puts auto in front of it, and a browser that supports auto sizes the image by its layout instead. (code)
The older PhotoPress Gallery block (photopress/gallery) is no longer in the inserter. Existing blocks still render. To convert one, select it and use Transform › Gallery. The new core Gallery gets the matching layout, column width, row height, spacing, slideshow setting and caption setting. Captions turned off in the old block become Hide captions, and the captions themselves are kept.
The layouts add attributes to the block comment and classes and CSS variables at render time. None of it is written into the gallery's saved HTML, so a gallery cannot become invalid in the editor.
| Hook | Type | Code | Purpose |
|---|---|---|---|
register_block_type_args |
filter | gallery.php#L191 | Registers the photopress* attributes on core/gallery on the server. |
render_block_data |
filter | gallery.php#L84 | Loads a gallery's images and their metadata in one query before its image blocks render, when the gallery has a layout or a slideshow, or licensing is on. |
render_block_core/gallery |
filter | gallery.php#L231 | Adds the layout classes, data-pp-* attributes and --pp-* variables, each image's sizes and --pp-ar (aspect ratio), the hidden-captions class, and the inline layout script. |
enqueue_block_editor_assets |
action | gallery.php#L122 | Passes the layouts turned on in the Gallery tab to the editor as window.photopressGalleryLayouts. |
blocks.registerBlockType (JS filter) |
filter | gallery-layouts.js#L148 | Registers the same attributes in the editor, so they are kept when the post is saved. |
editor.BlockEdit (JS filter) |
filter | gallery-layouts.js#L564 | Adds the PhotoPress panel, the Masonry and Mosaic previews, and hides Columns. |
editor.BlockListBlock (JS filter) |
filter | gallery-layouts.js#L661 | Adds the layout classes and variables to the block in the editor canvas. |
Core functions and APIs relied on:
-
registerBlockVariationfor the Masonry, Rows and Mosaic Gallery variations, and the Gallery variation that returns to columns (code). -
WP_HTML_Tag_Processorto change the rendered gallery. -
wp_get_attachment_metadata()for each image's width and height (code). -
wp_get_inline_script_tag()for the inline layout script (code), not printed in feeds (is_feed()). -
wp_enqueue_script()fordist/gallery-layouts.build.js(handlephotopress-gallery-layouts, footer, no dependencies) (code). -
wp_add_inline_script()for the editor's list of layouts.
Scripts:
| File | Source | Loads | Does |
|---|---|---|---|
dist/gallery-layouts-inline.build.js |
gallery-layouts-inline.js | Inline, once, before the first Masonry or Mosaic gallery, with a one-line call after each gallery. | Adds the photopress-js class to <html>, lays the gallery out, adds photopress-laid-out. |
dist/gallery-layouts.build.js |
gallery-layouts.js | Footer, on pages with a Masonry or Mosaic gallery. | Lays out again and on width changes (ResizeObserver). |
Both use the same layout code as the editor: masonry.js and justify.js. The styles are in src/variations/style.scss.
Data stored:
| Where | Name | Contents |
|---|---|---|
| Option | photopress_core_gallery |
layout_masonry, layout_rows, layout_mosaic (booleans). Registered with register_setting() and show_in_rest. The settings tab reads and writes it through /wp/v2/settings. |
Block comment of core/gallery
|
photopressLayout |
masonry, rows or mosaic. Absent for columns. |
photopressColumnWidth |
Number, default 300. | |
photopressRowHeight |
Number, default 300. | |
photopressSlideshow |
Boolean, default false. | |
photopressHideCaptions |
Boolean, default false. |
Front-end markup added at render time:
| On | Added |
|---|---|
Gallery <figure>
|
Classes photopress-layout, photopress-layout-{layout}, photopress-hide-captions; attributes data-pp-column-width, data-pp-row-height; CSS variables --pp-column-width, --pp-row-height. |
Each image <figure>
|
Class photopress-gallery-item; data-position, data-id; CSS variable --pp-ar. |
Each <img>
|
data-position; sizes (in a layout). |
- Deactivating PhotoPress leaves the
photopress*attributes in the block comment. The galleries then render as core's columns. - Core offers no way to remove another block's control. PhotoPress hides Columns by finding the sidebar item labeled "Columns". The stored
columnsvalue is kept. - A Masonry or Mosaic gallery stays hidden until its layout script runs, for at most 3 seconds.
- If the browser blocks inline scripts (a Content Security Policy without a nonce), the footer script lays the gallery out and shows it.
- An image whose shape PhotoPress cannot find (no stored width and height, no
data-aspectratio) is taken as square in Mosaic and in thesizescalculation. - Turning a layout off in the Gallery tab does not change galleries that use it, on the page or in the editor.