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
import { ImageViewer, type LightboxImage } from "@/components/ui/image-viewer"
// The pictures are drawn here as SVG and passed as data URLs; a product passes its own files.
function drawing(shapes: string[]) {
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 800">
<rect width="1200" height="800" fill="#f7f7f7" />
${shapes.join("")}
</svg>`
return { src: `data:image/svg+xml,${encodeURIComponent(svg)}`, width: 1200, height: 800 }
}
const bars = Array.from({ length: 12 }, (_, i) => {
const height = 100 + i * 38
const opacity = (30 + i * 6) / 100
return `<rect x="${96 + i * 86}" y="${700 - height}" width="56" height="${height}" rx="8" fill="#5b45f5" opacity="${opacity}" />`
})
const rings = Array.from({ length: 5 }, (_, i) => {
const [radius, width, opacity] = [300 - i * 56, 2 + i * 3, (20 + i * 16) / 100]
return `<circle cx="600" cy="400" r="${radius}" fill="none" stroke="#191919" stroke-width="${width}" opacity="${opacity}" />`
})
const tiles = Array.from({ length: 24 }, (_, i) => {
const [x, y, opacity] = [156 + (i % 6) * 152, 100 + Math.floor(i / 6) * 152, (10 + Math.floor(i / 6) * 18) / 100]
return `<rect x="${x}" y="${y}" width="128" height="128" rx="16" fill="#191919" opacity="${opacity}" />`
})
const images: LightboxImage[] = [
{ id: "bars", alt: "Twelve bars that rise from left to right", caption: "Revenue by month", ...drawing(bars) },
{ id: "rings", alt: "Five rings that thicken towards the centre", caption: "Reach by channel", ...drawing(rings) },
{ id: "tiles", alt: "A grid of squares that darken row by row", caption: "Activity by week", ...drawing(tiles) },
]
export default function ImageViewerDefault() {
return <ImageViewer images={images} label="Report figures" thumbnailClassName="aspect-3/2 w-28" />
}
Custom parts
import {
ImageViewer,
ImageViewerCaption,
ImageViewerClose,
ImageViewerContent,
ImageViewerCounter,
ImageViewerGallery,
ImageViewerNext,
ImageViewerPrevious,
ImageViewerThumbnail,
type LightboxImage,
} from "@/components/ui/image-viewer"
// The pictures are gradients written here as SVG data URLs; a product passes its own files.
function gradient(from: string, to: string) {
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 900">
<linearGradient id="g" x2="1" y2="1">
<stop stop-color="${from}" />
<stop offset="1" stop-color="${to}" />
</linearGradient>
<rect width="1200" height="900" fill="url(#g)" />
</svg>`
return { src: `data:image/svg+xml,${encodeURIComponent(svg)}`, width: 1200, height: 900 }
}
const images: LightboxImage[] = [
{ id: "violet", alt: "A gradient from violet to pale grey", ...gradient("#5b45f5", "#f7f7f7") },
{ id: "ink", alt: "A gradient from near black to mid grey", ...gradient("#191919", "#8f8f8f") },
{ id: "mist", alt: "A gradient from white to soft violet", ...gradient("#ffffff", "#9a8cff") },
{ id: "dusk", alt: "A gradient from deep violet to near black", ...gradient("#3a2ab8", "#191919") },
]
export default function ImageViewerCustomParts() {
return (
<ImageViewer images={images} label="Project covers">
<ImageViewerGallery className="grid w-full max-w-sm grid-cols-2 gap-2">
{images.map((image) => (
<ImageViewerThumbnail key={image.id} imageId={image.id} className="aspect-4/3" />
))}
</ImageViewerGallery>
<ImageViewerContent
header={
<>
<ImageViewerCaption className="text-left" />
<ImageViewerClose />
</>
}
>
<ImageViewerPrevious />
<ImageViewerCounter />
<ImageViewerNext />
</ImageViewerContent>
</ImageViewer>
)
}
Controlled
"use client"
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { ImageViewer, type LightboxImage } from "@/components/ui/image-viewer"
// The pictures are drawn here as SVG and passed as data URLs; a product passes its own files.
function drawing(shapes: string) {
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 800">
<rect width="1200" height="800" fill="#f7f7f7" />
${shapes}
</svg>`
return { src: `data:image/svg+xml,${encodeURIComponent(svg)}`, width: 1200, height: 800 }
}
const before = `<g fill="#191919" opacity="0.25">
<rect x="200" y="120" width="800" height="160" rx="16" />
<rect x="200" y="320" width="800" height="160" rx="16" />
<rect x="200" y="520" width="800" height="160" rx="16" />
</g>`
const after = `<rect x="200" y="120" width="800" height="240" rx="16" fill="#5b45f5" opacity="0.7" />
<g fill="#191919" opacity="0.25">
<rect x="200" y="400" width="384" height="280" rx="16" />
<rect x="616" y="400" width="384" height="280" rx="16" />
</g>`
const images: LightboxImage[] = [
{ id: "before", alt: "Three wide blocks stacked in one column", caption: "Layout before", ...drawing(before) },
{ id: "after", alt: "One wide block above two blocks side by side", caption: "Layout after", ...drawing(after) },
]
export default function ImageViewerControlled() {
const [open, setOpen] = useState<string | null>(null)
return (
<div className="flex flex-col items-center gap-4">
<ImageViewer
images={images}
value={open}
onValueChange={setOpen}
label="Layout comparison"
thumbnailClassName="aspect-3/2 w-28"
renderCaption={(image) => `${image.caption}: ${image.alt.toLowerCase()}`}
/>
<Button variant="outline" onClick={() => setOpen("after")}>
Open the layout after
</Button>
</div>
)
}
Installation
npx shadcn@latest add @khaeli/image-viewerbunx --bun shadcn@latest add @khaeli/image-viewerInstall @khaeli/foundation first: this item's styling lives in its tokens and [data-slot] rules.
Installs with
- Registry items
- 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
altthat says what it shows. It names the picture, and the thumbnail button is named Open followed by that text. labelnames 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 itsaltwhen 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