Many pictures as a grid or a scroll-snap strip: lazy tiles that keep their aspect, skeleton, hidden and broken states, single or multiple picking, and a lightbox with arrow keys and Esc.
Image grid dataset
Install
npx shadcn add @syncrobotic/image-grid Also installs: lucide-react, @syncrobotic/cn, @syncrobotic/button, @syncrobotic/dialog, @syncrobotic/restricted-preview, @syncrobotic/skeleton
Overview
Many pictures at once, as a grid or a strip, that open in a lightbox or are picked one or many at a time.
When to use
- A dataset's images, the frames of a run, a camera's snapshots.
- Picking a cover picture, or the frames to send for labelling.
- What was just uploaded, as a strip under the upload field.
Use something else
- Files that are not pictures, or a queue with progress: Attachment.
- One preview someone must ask to see: Restricted preview.
More examples
States and real uses. Each example is also a Storybook story and a visual regression test.
Cover: aisle-0003.jpg
Image grid pick one
3 selected
Image grid pick many
6 pictures uploaded
Image grid strip after upload
Image grid hidden
Loading pictures
Image grid loading
Image grid broken
Usage rules
- Every tile keeps its aspect box before and after the picture loads, so the grid never jumps; pictures load lazily.
- Give each picture an alt that says what it shows, and its file name: the name is what a broken tile and the lightbox title show.
- Picked tiles are ringed in the focus ink with a check, never a status colour. While picking, the corner button opens the lightbox.
- Pictures the viewer must ask to see are
restricted, with areason; nothing loads before they ask. Log the view inonReveal. - Use the strip for a short row, such as what was just uploaded; for a whole dataset, the grid.
Changelog
- 0.17.42026-11-21The lightbox keeps the last picture in state set during render instead of a ref written during render, so it is safe under the React Compiler. No visible change.
- 0.17.32026-11-19File names stay whole when a tile is cropped; an unchecked box is an outline; the zoom button is smaller on small tiles.
- 0.16.02026-11-19First release: a gallery of thumbnails as a grid or a scroll-snap strip. Tiles keep their aspect box and load lazily; skeleton tiles while loading, hidden pictures through RestrictedPreview, a broken picture shows its file name. Single or multiple picking (aria-pressed, a ring in the focus ink and a check). A lightbox on Dialog with the position (3 of 24), ← → to move, Esc to close, focus back on the tile.