Skip to content
Design System
GitHub

Image grid

v0.17.4Beta

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

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 a reason; nothing loads before they ask. Log the view in onReveal.
  • 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.

How to upgrade