lightbox grid.md
Lightbox Grid
A photo grid whose thumbnails grow into a full view and fly back to their slot when you drag them down.
Source: https://kokonutui.com/docs/cards/lightbox-grid
Installation
npx shadcn@latest add @kokonutui/lightbox-grid
Props
| Prop | Type | Default | Description |
|---|---|---|---|
images? |
LightboxImage[] |
built-in |
|
className? |
string |
Extra classes for the root element. |
LightboxImage
| Field | Type | Description |
|---|---|---|
src |
string |
|
alt |
string |
|
width |
number |
Natural size, used to fit the open view without waiting for a load. |
height |
number |
|
caption? |
string |
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Lightbox Grid
* @version: 1.0.0
* @date: 2026-10-15
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import {
animate,
type MotionValue,
motion,
useMotionValue,
useReducedMotion,
useTransform,
} from "motion/react";
import Image from "next/image";
import {
type KeyboardEvent,
type PointerEvent,
type ReactNode,
type Ref,
useCallback,
useEffect,
useRef,
useState,
} from "react";
import { createPortal } from "react-dom";
import { cn } from "@/lib/utils";
export interface LightboxImage {
src: string;
alt: string;
/** Natural size, used to fit the open view without waiting for a load. */
width: number;
height: number;
caption?: string;
}
export interface LightboxGridProps {
images?: LightboxImage[];
className?: string;
}
const unsplash = (id: string, w: number, h: number) =>
`https://images.unsplash.com/photo-${id}?w=${w}&h=${h}&fit=crop&auto=format&q=80`;
const DEFAULT_IMAGES: LightboxImage[] = [
{
src: unsplash("1501785888041-af3ef285b470", 1600, 1067),
alt: "A lake below mountains",
width: 1600,
height: 1067,
caption: "Lake shore, early morning",
},
{
src: unsplash("1506905925346-21bda4d32df4", 1200, 1600),
alt: "Peaks above the clouds",
width: 1200,
height: 1600,
caption: "Above the cloud line",
},
{
src: unsplash("1470071459604-3b5ec3a7fe05", 1600, 1067),
alt: "Misty hills",
width: 1600,
height: 1067,
caption: "Fog over the hills",
},
{
src: unsplash("1441974231531-c6227db76b6e", 1200, 1600),
alt: "Light through a forest",
width: 1200,
height: 1600,
caption: "Forest, late afternoon",
},
{
src: unsplash("1469474968028-56623f02e42e", 1600, 1067),
alt: "Sun setting over a valley",
width: 1600,
height: 1067,
caption: "Valley at sunset",
},
{
src: unsplash("1433086966358-54859d0ed716", 1200, 1600),
alt: "A waterfall",
width: 1200,
height: 1600,
caption: "Waterfall after rain",
},
];
// ... (truncated for brevity)
/**
* A photo grid whose thumbnails grow into a full view. The open photo is the
* same element at every moment: a transform and a crop take it from its
* slot to the middle of the screen and back, wherever it was dragged to.
*/
export default function LightboxGrid({
images = DEFAULT_IMAGES,
className,
}: LightboxGridProps) {
const [active, setActive] = useState<number | null>(null);
const [rect, setRect] = useState<Rect | null>(null);
const [settled, setSettled] = useState(false);
const [closing, setClosing] = useState(false);
const thumbs = useRef<(HTMLButtonElement | null)[]>([]);
const closeTimer = useRef(0);
const reduceMotion = useReducedMotion();
const x = useMotionValue(0);
const y = useMotionValue(0);
const scale = useMotionValue(1);
const clip = useMotionValue(openClip());
const alpha = useMotionValue(1);
const fade = useMotionValue(0);
const frameFor = useCallback(
(index: number, open: Rect): Frame | null => {
const thumb = thumbs.current[index];
if (!thumb) {
return null;
}
const box = thumb.getBoundingClientRect();
if (!isVisible(box)) {
return null;
}
const radius =
Number.parseFloat(getComputedStyle(thumb).borderTopLeftRadius) || 0;
return thumbFrame(open, box, images[index], radius);
},
[images]
);
const open = useCallback(
(index: number) => {
const target = fitRect(images[index]);
const from = frameFor(index, target);
setActive(index);
setRect(target);
setClosing(false);
setSettled(false);
alpha.set(1);
if (!from || reduceMotion) {
x.set(0);
y.set(0);
scale.set(1);
clip.set(openClip());
fade.set(0);
alpha.set(0);
animate(alpha, 1, { duration: 0.18 });
animate(fade, 1, { duration: 0.18 }).then(() => setSettled(true));
return;
}
x.set(from.x);
y.set(from.y);
scale.set(from.scale);
clip.set(from.clip);
fade.set(0);
animate(x, 0, OPEN);
animate(y, 0, OPEN);
animate(scale, 1, OPEN);
animate(clip, openClip(), OPEN);
animate(fade, 1, { duration: 0.3, ease: EASE }).then(() =>
setSettled(true)
);
},
[alpha, clip, fade, frameFor, images, reduceMotion, scale, x, y]
);
const close = useCallback(
(velocity?: { x: number; y: number }) => {
if (active === null || !rect || closing) {
return;
}
setClosing(true);
const index = active;
thumbs.current[index]?.scrollIntoView({
behavior: "instant",
block: "nearest",
inline: "nearest",
});
const to = frameFor(index, rect);
const finish = () => {
setActive(null);
setRect(null);
setClosing(false);
thumbs.current[index]?.focus({ preventScroll: true });
};
if (!to || reduceMotion) {
animate(alpha, 0, { duration: 0.16 });
animate(fade, 0, { duration: 0.16 }).then(finish);
return;
}
const vx = (velocity?.x ?? 0) * 1000;
const vy = (velocity?.y ?? 0) * 1000;
animate(x, to.x, { ...CLOSE, velocity: vx });
animate(y, to.y, { ...CLOSE, velocity: vy });
animate(scale, to.scale, CLOSE);
animate(clip, to.clip, CLOSE);
animate(fade, 0, { duration: 0.28, ease: EASE });
closeTimer.current = window.setTimeout(finish, 420);
},
[
active,
alpha,
clip,
closing,
fade,
frameFor,
rect,
reduceMotion,
scale,
x,
y,
]
);
const step = useCallback(
(direction: 1 | -1) => {
if (active === null || closing) {
return;
}
const next = active + direction;
if (next < 0 || next >= images.length) {
return;
}
setActive(next);
setRect(fitRect(images[next]));
y.set(0);
scale.set(1);
clip.set(openClip());
fade.set(1);
if (reduceMotion) {
x.set(0);
alpha.set(1);
return;
}
x.set(direction * 72);
alpha.set(0);
animate(x, 0, { duration: 0.32, ease: EASE });
animate(alpha, 1, { duration: 0.22, ease: EASE });
},
[active, alpha, clip, closing, fade, images, reduceMotion, scale, x, y]
);
useEffect(() => () => window.clearTimeout(closeTimer.current), []);
useEffect(() => {
if (active === null) {
return;
}
const root = document.documentElement;
const previous = root.style.overflow;
root.style.overflow = "hidden";
const onResize = () => setRect(fitRect(images[active]));
window.addEventListener("resize", onResize);
return () => {
root.style.overflow = previous;
window.removeEventListener("resize", onResize);
};
}, [active, images]);
return (
<div className={cn("w-full max-w-xl", className)}>
<ul className="grid grid-cols-3 gap-2">
{images.map((image, index) => (
<li
className={cn(index === 0 && "col-span-2 row-span-2")}
key={image.src}
>
<button
aria-label={`Open ${image.alt}`}
className="relative block aspect-square w-full overflow-hidden rounded-xl bg-zinc-100 outline-offset-2 focus-visible:outline-2 focus-visible:outline-zinc-900 dark:bg-zinc-800 dark:focus-visible:outline-white"
onClick={() => open(index)}
ref={(node) => {
thumbs.current[index] = node;
}}
style={{ opacity: active === index ? 0 : 1 }}
type="button"
>
<Image
alt=""
className="h-full w-full object-cover transition-[filter] duration-200 hover:brightness-95"
draggable={false}
fill
sizes="(max-width: 640px) 66vw, 384px"
src={image.src}
unoptimized
/>
</button>
</li>
))}
</ul>
{active !== null && rect
? createPortal(
<Viewer
alpha={alpha}
clip={clip}
fade={fade}
images={images}
index={active}
onClose={close}
onStep={step}
rect={rect}
scale={scale}
settled={settled && !closing}
x={x}
y={y}
/>,
document.body
)
: null}
</div>
);
}