Screenshot UI for plugin directory

[hlashbrooke]

The screenshot UI in the new plugin directory is good, but it could do with a couple of tweaks to make it more streamlined.

I'll refer to this plugin of mine as an example as it has a lot (too many!) screenshots: ​https://wordpress.org/plugins-wp/seriously-simple-podcasting/

1. The number of screenshots should be limited. I believe this has been discussed before, but a limit of 4-6 images would be best I think. Once that is done, then the thumbnail carousel images should be resized to fit exactly the maximum number of screenshots under the displayed image.

2. When the displayed image changes, the image height should be changed with an animated slide (even if it's a fast one) to prevent jarring UI changes when images of vastly different heights are used.

3. We should add a lightbox to the displayed image so people can see it more clearly in cases where the image contains small text. Something like the Featherlight lightbox library might be good as it has a very minimal UI that won't look out of place in the new directory.

Those updates would make the screenshot UI a whole lot smoother and easier to use.

[chriscct7]

Replying to hlashbrooke:

1. The number of screenshots should be limited. I believe this has been discussed before, but a limit of 4-6 images would be best I think. Once that is done, then the thumbnail carousel images should be resized to fit exactly the maximum number of screenshots under the displayed image.

I think your plugin shows the usecase as to why there shouldn't be a limit. Screenshots are supposed to provide users context to a plugin, like being able to see what options do and don't exist, and how things will be output. Limiting screenshots seems counterintuitive to a goal of making the directory better for the end users, who by definition are on the directory trying to find a plugin that meets their needs. If the number of screenshots is limited, on certain plugins, particularly ones with more settings than others (WooCommerce, EDD, any caching plugin, etc), it will be significantly harder for users to gauge if they've found the right plugin without needing to install it to see.

[chriscct7]

A good example is the plugins page for Easy Digital Downloads. It demonstrates the types of screenshots users expect to see for an eCommerce plugin:

• What does the checkout screen look like
• What does the reporting look like
• What does the edit order screen look like
• What does the edit product screen look like (and what options are there)
• What settings does the plugin offer
• How flexible are coupons
• etc etc

There's a lot more than 6 screenshots needed for a user to answer these relatively basic questions about a plugin.

[hlashbrooke]

@chriscct7: Yeah fair point - allowing a ton of screenshots isn't a huge issue really, just so long as the UI for viewing them can handle it. Right now, they all stick off the right of the viewport, which really isn't ideal at all. We would need to work out a better way to display them.

[chriscct7]

Instead of having 1 large image + tons of tiny images in a row underneath it, perhaps have a grid of images 3 - 5 columns wide per row, with the ability to click to expand on an overlay. This would allow for tons of images to be handled.

[chriscct7]

Now that I think of it, the issue that will run into is the images can be different ratios. Perhaps a masonry style grid?

[hlashbrooke]

Something that I thought of that could work nicely is larger thumbnails in 3 columns using a masonry layout (so the ratios don't matter) and then clicking on them pops up a lightbox. That would give you a way to see all of the screenshots at a glance without even having to click on anything, but it would also allow for viewing them in greater detail.

So screenshots of a widget UI would be pretty easy to see without expanding, but if it's a screenshot of a longer settings screen then the user could click on it.

[tellyworth]

Here's an example of screenshots that would benefit from some way to zoom, as suggested in (3):

​https://wordpress.org/plugins-wp/string-locator/

[Goran87]

Clicking on the image has same effect as a lightbox, except that its not lightbox. Its pretty confusing, i tried to hit escape, then was looking for close button untill I hit back. I definitely agree that there should be some kind of simple lightbox, or to have it open as standard image in browser, current solution is very confusing to the end user.

[brianhogg]

I also ran into this yesterday, hitting escape and clicking around thinking I was still on the plugin page. Should either be in a lightbox or remove the link to the full image for the time being?

[lukecavanagh]

Using something like this would be a lightweight option for a lightbox.

​https://github.com/noelboss/featherlight/
​https://github.com/nicolas-t/Chocolat

[kevinwhoffman]

I feel we need a real lightbox solution to improve the experience. I'd like to suggest Magnific which does several things really well to solve some of the issues mentioned above:

• Elegant lightbox UI
• Keyboard-accessible (focuses correctly on popup, arrow navigation, escape to close)
• Touch-enabled
• Supports captions
• Supports galleries
• Keeps the gallery experience on one page (current implementation launches an entirely new page per image)
• Allows user to navigate from one zoomed-in image to the next without having to exit back to the main page in between

Check out the Lightbox gallery example on this page: ​http://dimsemenov.com/plugins/magnific-popup/

[lukecavanagh]

Magnific Popup does look very solid, the JS is a bit bigger than the two other previous examples, around 19kb, but it does handle a lot.

Replying to kevinwhoffman:

I feel we need a real lightbox solution to improve the experience. I'd like to suggest Magnific which does several things really well to solve some of the issues mentioned above:

• Elegant lightbox UI
• Keyboard-accessible (focuses correctly on popup, arrow navigation, escape to close)
• Touch-enabled
• Supports captions
• Supports galleries
• Keeps the gallery experience on one page (current implementation launches an entirely new page per image)
• Allows user to navigate from one zoomed-in image to the next without having to exit back to the main page in between

Check out the Lightbox gallery example on this page: ​http://dimsemenov.com/plugins/magnific-popup/

[ck3lee]

Attached a patch attachment:2273-1.diff​ with screen capture. I hope to get some dev and UI feedback first before working on final patch.

• Still a WIP.
• Fix the bouncing height issue. The drawback of this is a smaller.
• Add lightbox for fullscreen view. There is still CSS work to do for the fullscreen view
• Improve on accessibility with keyboard nav for previous and next buttons - without hover.
• Looks like existing code is in React and was a fork of this package ​https://www.npmjs.com/package/react-image-gallery. So, I kept try to keep it the same by using this library.

[SergeyBiryukov]

#4743 was marked as a duplicate.

[MarcosAlexandre]

@ck3lee Thanks for your patch! As the ticket has been open for some time, there have been updates to the react-image-gallery package, so I made some minor adjustments:

I changed the version in the package.json file to 1.0.7 and also made some adjustments to the image-gallery-lightbox / style.scss file name. If you can test that everything is still right on your side, I will be happy ;)

@SergeyBiryukov Although this ticket is not a priority, it has been open for 4 years to correct the usability of the plugins page. How can we move this ticket forward?

This PR uses the previous work done in 2273 + react-image-gallery to improve the screenshot UI.

The improvements:

• The screenshots are now a consistent height, which prevents content jump.
• This library also provides a "lightbox" view for viewing larger images at full-size.
• The keyboard navigation experience is also improved: next, previous, and full-screen buttons all have focus states.

Unfortunately, there are issues too. The transition CSS on RTL pages is a little janky, and the labels used in the library are also not available for translation, so non-English screen reader users will still hear English labels.

Screenshot UI:

The thumbnail nav on RTL + many screenshots ends up veering offscreen somehow, I think the offset logic must be wrong in react-image-gallery, or the CSS here conflicts with it somehow.

Fullscreen (lightbox) view:

---

https://meta.trac.wordpress.org/ticket/2273

[ryelle]

I've attached a PR which updates the react-image-gallery approach — I almost committed it, but you can see in the PR, there are some issues with RTL and translations that make me think we should revisit this library. Maybe there are some gutenberg components we can use instead?

[dd32]

#6896 was marked as a duplicate.

[blackstar1991]

Sounds like a really good idea. Who can help with the implementation?

[takshil]

Hi @dd32 & folks. I'd be happy to pick this up :)

[dd32]

Looks like the image parts of this ticket are being resolved via #8083

See ​https://github.com/WordPress/wordpress.org/pull/524#issuecomment-4060518452 for the latest work

Replaces the bespoke wporg-plugins-2024 theme JS screenshots gallery with a server-rendered [wporg-plugins-screenshots] shortcode in the Plugin Directory plugin, and adds a small polyfill plugin (Gallery Lightbox Enhancements) that restores two long-standing Gutenberg gaps locally so the wp.org migration can ship without waiting on core.

## Visual evidence

### Layout cases — counts 1 to 9

Case	Screenshot
N=1 — single tile, max-width 720 px
N=2 — 2-col row-aligned grid
N=4 — 3-up grid + last figure as full-width anchor
N=5 — 3+2 row-aligned grid
N=6 — 3×2 grid
N=6 — 3×2 grid
N=7, mixed aspect — brick masonry, natural ratios preserved
N=8 — brick masonry
N=9 (reveal threshold edge) — full grid, no Show-all button

### Reveal flow (N≥10)

State	Screenshot
Show-all button + fade overlay — collapsed wrap clipped at 32rem
After Show-all click — wrap unfolds to full content, fade and button removed

### Mobile (≤599 px)

Case	Screenshot
Collapse suppressed — every figure rendered, no fade or Show-all button on small viewports
N=33 mobile — full gallery, vertical scroll only

## What changes

• wp-content/plugins/plugin-directory/shortcodes/class-screenshots.php — new shortcode that renders every screenshot through core/gallery + core/image blocks, lightbox enabled per tile. Galleries up to 9 figures show the full grid; larger ones get a Show all N screenshots reveal button. Layout is deterministic: N=1 single tile, N=2-4 row-aligned grid, N≥5 brick masonry by default with a row-aligned grid upgrade when every screenshot shares an aspect ratio.
• wp-content/plugins/gallery-lightbox-enhancements/ — polyfill plugin that adds a is-style-masonry block style for core/gallery and renders figcaption text inside the lightbox overlay. Both behaviours are gated behind Version_Guard::should_load(), which lets the plugin self-disable once core ships the features.
• wp-content/themes/pub/wporg-plugins-2024/ — removes the legacy theme implementation: client/screenshots/, the dedicated theme.js entry, the matching SCSS partials, and the build:old:js npm script.

## Why

Server-side rendering makes the gallery cacheable by Varnish, works without JS, and gives third-party scrapers and SEO crawlers the full markup. Every <img> ships with loading="eager", intrinsic width / height attributes, and fetchpriority="high" on the cap-window thumbnails, so CLS stays at 0 while screenshots decode. Aspect ratios and pixel dimensions come from a single Memcached-cached probe (md5-keyed by URL list, so a screenshot revision auto-invalidates).

## Closes / refs

Meta Trac (the long-standing screenshot UX gaps this PR addresses):

• Closes meta#2273 — Screenshot UI redesign (open ~9 years, primary tracking ticket)
• Closes meta#8083 — Add lightbox for plugin screenshots
• Closes meta#8204 — Chrome 146 table-cell layout bug (the new shortcode renders through CSS Grid / columns, the legacy table-cell path is dropped)
• Refs meta#5190 — Lazy loading screenshots (we go the opposite way: eager + fetchpriority, see "Why" above)
• Refs meta#7878 — Screenshot navigation (handled by the core lightbox arrows)

Upstream Gutenberg gaps that the polyfill plugin addresses on the user side:

• ​gutenberg#28247 — Gallery masonry layout (open since January 2021)
• ​gutenberg#60469 — Lightbox captions excluded from overlay (regression since WP 6.5)

## Prior art on this task

Earlier attempts at the same migration that fed into this PR's design:

• ​WordPress/wordpress.org#524 — @ryelle's Gallery block migration draft.
• ​WordPress/wordpress.org#67 — older screenshot redesign attempt (predates Gutenberg gallery, kept for context).
• ​WordPress/wporg-parent-2021#178 — lightbox component on the parent theme.

## Safety / scope

The change is additive on the Plugin Directory side and isolated for the polyfill, with one purposeful subtraction in the theme. Map of every touched path:

Path	Risk
wp-content/plugins/gallery-lightbox-enhancements/ (new plugin, 9 files)	None on its own. Self-disables via Version_Guard::should_load() once core ships the features. Activation lives outside this PR (mu-plugin loader on production).
wp-content/plugins/plugin-directory/shortcodes/class-screenshots.php	Rewritten body, same registration hook. Shortcode tag, file name and class FQN are unchanged, so anything that already calls do_shortcode( '[wporg-plugins-screenshots]' ) keeps working.
wp-content/plugins/plugin-directory/shortcodes/assets/screenshots.css, screenshots.js	New files. Enqueued only inside the shortcode's render path, so other pages on wp.org/plugins do not load them.
wp-content/plugins/plugin-directory/class-plugin-directory.php (+2)	One add_action( 'wp_head', [ Screenshots::class, 'emit_preconnect' ] ) for <link rel="preconnect"> to the Photon host. Hint only, no blocking behaviour.
wp-content/themes/pub/wporg-plugins-2024/client/screenshots/ (deleted)	Main subtraction. A repo-wide grep finds no external imports of these modules; happy to add a shim if a downstream consumer is missed.
wp-content/themes/pub/wporg-plugins-2024/css/style.css, style-rtl.css	Regenerated build artefacts after dropping the screenshot SCSS partials and the build:old:js script. No theme JS or CSS for screenshots remains — the shortcode owns the whole flow.

The migration does not touch DB schema, post types, taxonomies, REST endpoints, or any sibling shortcode in plugin-directory/shortcodes/.

## Notes for reviewers

• All PHP passes the project phpcs.xml.dist ruleset (WordPress-Core / Docs / Extra, PHP 8.4 compat).
• No theme JS or CSS left for screenshots — the shortcode owns the whole flow.
• Polyfill is fully self-contained: drop in, drop out once core ships the features.
• cc @dd32 — would value your eyes on the Version_Guard placeholder strategy and on the deletion of the old client/screenshots/ modules.
• cc @ryelle — this picks up the direction from #524; happy to align further on the layout decisions if you have feedback.

A bit of context on how we got here: we first proposed an upstream Gutenberg fix for lightbox captions and, separately, a masonry block style for core/gallery. The masonry proposal was declined upstream and the captions one has not had movement; rather than block the wp.org migration on either, we ship the same behaviour as a self-disabling polyfill plugin so the gallery on wordpress.org/plugins/{slug}/ can move forward today. If either fix lands in core later, flip Version_Guard::CORE_VERSION_WITH_FEATURES to that release tag and the plugin steps aside.

On captions specifically: every figure ships its caption text, but it surfaces only inside the lightbox overlay and never on the gallery itself. Plugin authors routinely write multi-sentence captions, and rendering those under each thumbnail would tear the brick layout apart with uneven figure heights. The lightbox is the right surface for that copy - it has room for it without compromising the grid.