Block-Picker thumbnails that generate themselves

Payload's block editor accepts an imageURL per block type. Set one and editors see a thumbnail in the picker. Leave it out and they see a list of names, "Directional List," "Radial Cards," "Content Block", and have to guess what each one looks like.

We have 27 layout blocks. Once the library got past ten or so, the name-only picker became a friction point. Editors would add a block, realise it wasn't what they wanted, delete it, and try another. Or they'd stick with the three blocks they recognised and ignore the rest.

The block library is only useful if editors can find what they need. Thumbnails solve this, but 27 blocks is a lot of images to create and maintain.

We considered creating thumbnails in Figma. The problem is maintenance. Every time a block's design changes, new spacing, a different font size, an updated colour, someone has to remember to update the mockup. Nobody does. The thumbnail drifts from reality and editors are back to guessing.

Real screenshots are always current. Run the command after a deploy and the thumbnails reflect exactly what visitors see. If a block looks different on the site, it looks different in the picker.

The command is pnpm thumbnails:blocks. It screenshots every block from the live site and outputs a framed WebP thumbnail. The whole set takes a few minutes. The result is 27 thumbnails, each 2–17 KB, stored at public/blocks/<slug>.webp.

Each block config references its thumbnail:

json
1// src/blocks/ContentBlock/config.ts
2{
3  slug: 'contentBlock',
4  imageURL: '/blocks/contentBlock.webp',
5  // ...fields
6}

You don't have to regenerate all 27 every time. Pass block slugs as arguments to regenerate only the ones you name:

bash
1pnpm thumbnails:blocks contentBlock teamBlock

The script targets the live site by default — real published content with production media, exactly as visitors see it. You can point it at a different environment with BASE_URL:

bash
1BASE_URL=https://staging.littledash.com.au pnpm thumbnails:blocks

A local build works too as long as the media is available locally, but the live site is the most reliable source because our media is stored in S3.

Transparent page body. The site's background colour is set at a higher level, so block screenshots come back with a transparent background. The sharp step fills this in with #F7F7F5 when it creates the framed thumbnail. Without this, the thumbnails would have a checkerboard or black background in the admin panel.

Parallax and overlapping layouts. Some blocks intentionally overflow their container, a parallax hero that moves on scroll, or a section with negative margin pulling it into the block above. The 120-pixel overflow cap and overflow-clip detection handle most of these. The result isn't pixel-perfect for every block, but it's accurate enough for a picker thumbnail.

Blocks with no published usage. If a block type exists in the code but isn't used on any published page, there's nothing to screenshot. The script lists these at the end. If a block has been in the codebase for months with zero usage, it's worth asking whether it should stay.