<?php
function bbioon_render_plugin_screenshots( array $screenshots ): string {
$inner = '';
foreach ( $screenshots as $shot ) {
$inner .= sprintf(
'<!-- wp:image {"sizeSlug":"large","lightbox":{"enabled":true}} -->
<figure class="wp-block-image"><img src="%1$s" alt="" /><figcaption class="wp-element-caption">%2$s</figcaption></figure>
<!-- /wp:image -->',
esc_url( $shot['src'] ),
esc_html( $shot['caption'] )
);
}
return do_blocks(
'<!-- wp:gallery {"columns":3} -->
<figure class="wp-block-gallery has-nested-images columns-3">' . $inner . '</figure>
<!-- /wp:gallery -->'
);
}That is close to what WordPress.org now runs on every plugin page. The Plugin Directory screenshots gallery was rebuilt to render screenshots on the server with the core Gallery and Image blocks and the standard WordPress lightbox, and Dan Zakirov wrote the whole thing up on Make WordPress. The design is fine, but the part I keep thinking about is the process: the masonry layout was proposed for core first, core said no, and the directory shipped it scoped to itself anyway. That sequence is worth copying on client work, so here is what landed and why I like it.
What the Plugin Directory screenshots gallery does now
The work was tracked in WordPress.org PR 622 and it closes the main part of Meta Trac 2273, a screenshots task that had been open for about nine years. Rendering goes through do_blocks(), so the lightbox, the captions, and the markup all come from core rather than from a directory-specific script. The new behavior is opt in and the styles are scoped, so existing galleries stay untouched. That matters when a change lands on tens of thousands of plugin pages at once. The gallery also reads the image count and the available dimensions, and picks a grid for visually uniform sets and a masonry layout for mixed ones, so tall and panoramic screenshots keep their natural proportions instead of getting cropped.
Why core turned down the masonry part
The first attempt was upstream rather than a local patch. Two Gutenberg pull requests came out of it, one for lightbox captions and one for a masonry style on the Gallery block. The feedback on the masonry one was that it should not land in core in its current form, and that it belongs in plugin or theme territory until a cleaner browser-level CSS masonry solution exists. I think that feedback was right, and the browser situation backs it up. Native masonry finally shipped as display: grid-lanes in Safari 26.4 in March 2026, but MDN still flags it as limited availability because Chrome and Firefox have not shipped it stable. Core would have been maintaining a workaround for years.
What the directory did instead is a reasonable middle ground. Since the upstream path had no near-term timeline, it kept the compatible masonry behavior scoped to WordPress.org instead of leaving the old gallery in place for several more years. The core markup stays, the extra layout is scoped CSS, and the source says the implementation can be adapted as the upstream work evolves. That split between block output and layout is what makes a future swap easy. I would have made the same call for a client site.
How I’d build the same thing
Start from the code at the top. Build the gallery and image block markup on the server, run it through do_blocks(), and print the result. The core lightbox script and the gallery block styles get enqueued the normal way, because WordPress sees real block markup, and your own CSS only adds layout on a class you control. Do not cache the rendered HTML for long, because core has changed gallery markup more than once and stored output goes stale. Writing the final figure markup by hand is also a mistake, since parsing and rendering on request is cheaper to maintain than a frozen copy. The reference for do_blocks() is short and worth a read if you have only ever seen it inside the loop.
If you maintain plugins in the directory, or you want a screenshots gallery on a client site that behaves like this without a custom lightbox, that is work I do regularly. It is a small build on top of core blocks, and it removes the need to maintain a lightbox of your own.
What to check first
Check your own screenshots tab before rewriting anything. The comments on the announcement turned up two live problems: thumbnails that do not refresh after uploading, and screenshots cut off in the modal, tracked in Meta Trac 8331. There is also a separate open accessibility ticket, 8289. If your gallery still looks awkward, post the slug on the Make post, because the team is asking for real examples. Give the readme a pass while you are in there, since the readme rules still get submissions held up.
And if you copy the pattern, test the ugly cases first: images with no width and height attributes, a gallery with one screenshot only, and a set where every image is a different ratio. Masonry hides those problems, grids expose them, and the directory now picks between the two based on the files you upload.
