Skip to content

Image viewer

A morphing lightbox with zoom, pan and swipe. Adapted from beUI (MIT).

Pass images and it draws the thumbnails and the viewer. Pass children instead to lay out the parts yourself, and value with onValueChange to open an image from elsewhere. It animates with motion, so it needs the @khaeli/motion-provider above it.

Default

Custom parts

Controlled

Installation

npx shadcn@latest add @khaeli/image-viewer

Install @khaeli/foundation first: this item's styling lives in its tokens and [data-slot] rules.

Installs with

npm packages
  • @keyline-icons/react ^2.2.0
  • motion ^12.23.12

Keyboard

EnterSpace
On a thumbnail, open the viewer at that image. Focus moves into the viewer.
Arrow RightArrow Left
Show the next and the previous image. They stop at the last and the first image.
+-0
Zoom in a step, zoom out a step, and go back to the whole image.
TabShift Tab
Move between the viewer's buttons and wrap at either end. Focus cannot leave the viewer while it is open.
Escape
Closes the viewer and returns focus to the thumbnail it was opened from.

Accessible name

  • Every image needs an alt that says what it shows. It names the picture, and the thumbnail button is named Open followed by that text.
  • label names the gallery and the viewer, which is a modal dialog. It defaults to Image gallery; set it to what the pictures are.
  • The item names its buttons Close viewer, Previous image and Next image.
  • The counter and the caption are announced when the image changes. The caption is the image's caption, or its alt when it has none.

Registry JSON

The item as the shadcn CLI reads it, with every file it ships: https://ui.khaeli.com/r/image-viewer.json