contact sheet.md
Contact Sheet
Pick from a shoot the way photographers do. Circle a frame in china marker, click again to strike it, and look through a loupe at the detail first.
Source: https://kokonutui.com/docs/media/contact-sheet
Installation
npx shadcn@latest add @kokonutui/contact-sheet
Props
| Prop | Type | Default | Description |
|---|---|---|---|
frames? |
ContactFrame[] |
demo |
|
perStrip? |
number |
4 |
Frames per strip. |
firstFrame? |
number |
12 |
Printed on the film edge before each frame number. |
title? |
string |
"Roll 14 · Lisbon" |
|
defaultMarks? |
Record<number, Mark> |
{ 1: "pick", 5: "reject", 8: "pick" } |
|
onExport? |
(picked: number[]) => void |
||
className? |
string |
Extra classes for the root element. |
ContactFrame
| Field | Type | Description |
|---|---|---|
src |
string |
A 3:2 image. |
alt |
string |
|
x? |
number |
Where this frame sits in the shot, 0 to 1. Frames from one scene differ a little. |
y? |
number |
|
zoom? |
number |
1 shows the whole image. |
Mark
type Mark = "pick" | "reject";
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Contact Sheet
* @version: 1.0.0
* @date: 2026-10-22
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import { Check, ZoomIn } from "lucide-react";
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
import {
type CSSProperties,
type KeyboardEvent,
type PointerEvent,
useRef,
useState,
} from "react";
import { cn } from "@/lib/utils";
/** How much the loupe magnifies, and its size in px. */
const ZOOM = 3;
const LOUPE = 136;
const DRAW_EASE = [0.6, 0, 0.3, 1] as const;
export interface ContactFrame {
/** A 3:2 image. */
src: string;
alt: string;
/** Where this frame sits in the shot, 0 to 1. Frames from one scene differ a little. */
x?: number;
y?: number;
/** 1 shows the whole image. */
zoom?: number;
}
type Mark = "pick" | "reject";
export interface ContactSheetProps {
frames?: ContactFrame[];
/** Frames per strip. */
perStrip?: number;
/** Printed on the film edge before each frame number. */
firstFrame?: number;
title?: string;
defaultMarks?: Record<number, Mark>;
onExport?: (picked: number[]) => void;
className?: string;
}
const unsplash = (id: string) =>
`https://images.unsplash.com/photo-${id}?w=900&h=600&fit=crop&auto=format&q=75`;
const LAKE = unsplash("1501785888041-af3ef285b470");
const RIDGE = unsplash("1506905925346-21bda4d32df4");
const FOG = unsplash("1470071459604-3b5ec3a7fe05");
const PINES = unsplash("1441974231531-c6227db76b6e");
const VALLEY = unsplash("1469474968028-56623f02e42e");
const PORTRAIT = unsplash("1534528741775-53994a69daeb");
const DEMO_FRAMES: ContactFrame[] = [
{ src: LAKE, alt: "Lake under mountains, wide", zoom: 1 },
{
src: LAKE,
alt: "Lake under mountains, closer",
zoom: 1.25,
x: 0.4,
y: 0.6,
},
{ src: FOG, alt: "Hills in fog", zoom: 1 },
{ src: FOG, alt: "Hills in fog, tighter", zoom: 1.3, x: 0.7, y: 0.5 },
{ src: PORTRAIT, alt: "Portrait, head and shoulders", zoom: 1, y: 0.3 },
{ src: PORTRAIT, alt: "Portrait, eyes closed in", zoom: 1.5, x: 0.5, y: 0.3 },
{ src: RIDGE, alt: "Ridge line at dusk", zoom: 1 },
{ src: RIDGE, alt: "Ridge line, the far peaks", zoom: 1.35, x: 0.85, y: 0.4 },
{ src: PINES, alt: "Pine forest, looking up", zoom: 1 },
{
src: PINES,
alt: "Pine forest, light through trunks",
zoom: 1.3,
x: 0.3,
y: 0.7,
},
{ src: VALLEY, alt: "Valley road", zoom: 1 },
{ src: VALLEY, alt: "Valley road, the bend", zoom: 1.4, x: 0.6, y: 0.75 },
];
/** A small seeded random, so every frame keeps its own wobble. */
const seeded = (seed: number) => {
let s = seed * 9301 + 49_297;
return () => {
s = (s * 9301 + 49_297) % 233_280;
return s / 233_280;
};
};
/**
* A china-marker loop: a lopsided ellipse that runs past where it started,
* drawn in a 100 x 100 box stretched over the frame.
*/
function loopPath(seed: number) {
const rand = seeded(seed + 1);
const start = -2.2 + rand() * 0.6;
const sweep = Math.PI * 2 + 0.35 + rand() * 0.3;
const tilt = (rand() - 0.5) * 0.12;
const steps = 56;
const points: string[] = [];
for (let i = 0; i <= steps; i++) {
const t = i / steps;
const a = start + sweep * t;
// The hand drifts outward as it goes round, so the ends don't meet.
const grow = 1 + t * 0.06;
const wobble = 1 + Math.sin(a * 3 + seed) * 0.015;
const rx = 52 * grow * wobble;
const ry = 55 * grow * wobble;
const x = 50 + Math.cos(a) * rx - Math.sin(a) * ry * tilt;
const y = 50 + Math.sin(a) * ry + Math.cos(a) * rx * tilt;
points.push(`${i === 0 ? "M" : "L"}${x.toFixed(2)} ${y.toFixed(2)}`);
}
return points.join(" ");
}
function MarkStroke({
mark,
index,
reduceMotion,
}: {
mark: Mark;
index: number;
reduceMotion: boolean;
}) {
const draw = (delay: number) => ({
initial: { pathLength: 0, opacity: 1 },
animate: { pathLength: 1, opacity: 1 },
transition: reduceMotion
? { duration: 0 }
: {
pathLength: { duration: 0.32, ease: DRAW_EASE, delay },
opacity: { duration: 0 },
},
});
const paths =
mark === "pick"
? [loopPath(index)]
: ["M14 16 Q 48 46 86 84", "M84 14 Q 54 50 16 86"];
return (
<motion.svg
aria-hidden="true"
className="pointer-events-none absolute -inset-1.5 z-10 h-[calc(100%+12px)] w-[calc(100%+12px)] overflow-visible text-red-600 dark:text-red-500"
exit={{ opacity: 0, transition: { duration: reduceMotion ? 0 : 0.15 } }}
preserveAspectRatio="none"
viewBox="0 0 100 100"
>
{paths.map((d, i) => (
<motion.path
d={d}
fill="none"
key={d}
stroke="currentColor"
strokeLinecap="round"
strokeLinejoin="round"
strokeWidth={3}
vectorEffect="non-scaling-stroke"
{...draw(i * 0.2)}
/>
))}
</motion.svg>
);
}
/** Image layer for a frame: the shot, framed and zoomed. */
const frameStyle = (frame: ContactFrame): CSSProperties => ({
backgroundImage: `url("${frame.src}")`,
backgroundSize: `${(frame.zoom ?? 1) * 100}%`,
backgroundPosition: `${(frame.x ?? 0.5) * 100}% ${(frame.y ?? 0.5) * 100}%`,
});
interface Lens {
frame: ContactFrame;
/** Loupe center, in the sheet's px. */
left: number;
top: number;
/** Background for the loupe. */
size: string;
position: string;
}
/** What the loupe shows over `frame`, for a pointer at (px, py) in it. */
function lensFor(
frame: ContactFrame,
rect: DOMRect,
px: number,
py: number
): Pick<Lens, "size" | "position"> {
const zoom = frame.zoom ?? 1;
const w = rect.width * zoom;
const h = rect.height * zoom;
const ix = px - (rect.width - w) * (frame.x ?? 0.5);
const iy = py - (rect.height - h) * (frame.y ?? 0.5);
return {
size: `${w * ZOOM}px ${h * ZOOM}px`,
position: `${LOUPE / 2 - ix * ZOOM}px ${LOUPE / 2 - iy * ZOOM}px`,
};
}
const nextMark = (mark: Mark | undefined): Mark | undefined => {
if (!mark) {
return "pick";
}
return mark === "pick" ? "reject" : undefined;
};
function Frame({
frame,
index,
number,
mark,
loupe,
reduceMotion,
onMark,
onLens,
onLeave,
}: {
frame: ContactFrame;
index: number;
number: number;
mark: Mark | undefined;
loupe: boolean;
reduceMotion: boolean;
onMark: (index: number, mark: Mark | undefined) => void;
onLens: (event: PointerEvent<HTMLButtonElement>, frame: ContactFrame) => void;
onLeave: () => void;
}) {
const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>) => {
const keys: Record<string, Mark | undefined> = {
p: mark === "pick" ? undefined : "pick",
x: mark === "reject" ? undefined : "reject",
Backspace: undefined,
};
if (event.key in keys) {
event.preventDefault();
onMark(index, keys[event.key]);
}
};
let state = "";
if (mark) {
state = mark === "pick" ? ", picked" : ", struck";
}
return (
<div className="relative">
<button
aria-label={`Frame ${number}: ${frame.alt}${state}`}
className={cn(
"relative block aspect-[3/2] w-full overflow-hidden bg-zinc-800 outline-none focus-visible:ring-2 focus-visible:ring-sky-400 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-950",
loupe && "cursor-none"
)}
onClick={() => {
// Lift the loupe so you see the mark go down.
onLeave();
onMark(index, nextMark(mark));
}}
onKeyDown={onKeyDown}
onPointerLeave={onLeave}
onPointerMove={(event) => onLens(event, frame)}
type="button"
>
<span
className={cn(
"absolute inset-0 bg-no-repeat transition-opacity duration-200",
mark === "reject" && "opacity-35"
)}
style={frameStyle(frame)}
/>
</button>
<AnimatePresence initial={false}>
{mark && (
<MarkStroke
index={index}
key={mark}
mark={mark}
reduceMotion={reduceMotion}
/>
)}
</AnimatePresence>
</div>
);
}
/** A row of sprocket holes along the film edge. */
function Sprockets() {
return (
<div
aria-hidden="true"
className="mx-1 h-[5px]"
style={{
backgroundImage:
"repeating-linear-gradient(to right, var(--paper) 0 7px, transparent 7px 14px)",
}}
/>
);
}
/**
* A photographer's contact sheet, for picking from a shoot. Click a frame to
* circle it in china marker, again to strike it out, and hover to look
* through a loupe at the detail before you decide.
*/
export default function ContactSheet({
frames = DEMO_FRAMES,
perStrip = 4,
firstFrame = 12,
title = "Roll 14 · Lisbon",
defaultMarks = { 1: "pick", 5: "reject", 8: "pick" },
onExport,
className,
}: ContactSheetProps) {
const [marks, setMarks] = useState<Record<number, Mark>>(defaultMarks);
const [lens, setLens] = useState<Lens | null>(null);
const [loupe, setLoupe] = useState(true);
const [exported, setExported] = useState(false);
const sheetRef = useRef<HTMLDivElement>(null);
const reduceMotion = Boolean(useReducedMotion());
const strips: number[][] = [];
for (let i = 0; i < frames.length; i += perStrip) {
strips.push(frames.slice(i, i + perStrip).map((_, k) => i + k));
}
const picked = Object.keys(marks)
.map(Number)
.filter((i) => marks[i] === "pick")
.sort((a, b) => a - b);
const struck = Object.values(marks).filter((m) => m === "reject").length;
const mark = (index: number, next: Mark | undefined) => {
setExported(false);
setMarks((current) => {
const copy = { ...current };
if (next) {
copy[index] = next;
} else {
Reflect.deleteProperty(copy, index);
}
return copy;
});
};
const onLens = (
event: PointerEvent<HTMLButtonElement>,
frame: ContactFrame
) => {
const sheet = sheetRef.current?.getBoundingClientRect();
if (!(loupe && sheet) || event.pointerType !== "mouse") {
setLens(null);
return;
}
const rect = event.currentTarget.getBoundingClientRect();
const px = event.clientX - rect.left;
const py = event.clientY - rect.top;
setLens({
frame,
left: event.clientX - sheet.left,
top: event.clientY - sheet.top,
...lensFor(frame, rect, px, py),
});
};
return (
<div
className={cn(
"relative w-full max-w-2xl rounded-2xl border border-zinc-200 bg-white p-4 [--paper:#ffffff] sm:p-6 dark:border-zinc-800 dark:bg-zinc-900 dark:[--paper:#18181b]",
className
)}
ref={sheetRef}
>
<div className="flex items-start justify-between gap-4">
<div className="leading-tight">
<p className="font-medium text-sm text-zinc-900 dark:text-zinc-100">
{title}
</p>
<p className="mt-0.5 text-xs text-zinc-500 dark:text-zinc-400">
Click to circle a frame, again to strike it.
</p>
</div>
<button
aria-pressed={loupe}
className={cn(
"flex h-8 shrink-0 items-center gap-1.5 rounded-full px-3 font-medium text-xs outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-zinc-400",
loupe
? "bg-zinc-900 text-white dark:bg-zinc-100 dark:text-zinc-900"
: "bg-zinc-100 text-zinc-600 hover:bg-zinc-200 dark:bg-zinc-800 dark:text-zinc-300 dark:hover:bg-zinc-700"
)}
onClick={() => setLoupe((on) => !on)}
type="button"
>
<ZoomIn aria-hidden className="size-3.5" />
Loupe
</button>
</div>
<div className="mt-4 space-y-3 sm:space-y-4">
{strips.map((strip, s) => (
<div className="rounded-[3px] bg-zinc-950 py-1" key={strip[0]}>
<Sprockets />
<div
className="mt-1 grid gap-1 px-1"
style={{ gridTemplateColumns: `repeat(${perStrip}, 1fr)` }}
>
{strip.map((i) => (
<Frame
frame={frames[i]}
index={i}
key={i}
loupe={loupe}
mark={marks[i]}
number={firstFrame + i}
onLeave={() => setLens(null)}
onLens={onLens}
onMark={mark}
reduceMotion={reduceMotion}
/>
))}
</div>
<div
aria-hidden="true"
className="mt-0.5 grid px-1 font-mono text-[8px] text-orange-300/70 leading-3 sm:text-[9px]"
style={{ gridTemplateColumns: `repeat(${perStrip}, 1fr)` }}
>
{strip.map((i) => (
<span className="flex justify-between px-1" key={i}>
<span>{firstFrame + i}</span>
<span>▸{firstFrame + i}A</span>
</span>
))}
</div>
<Sprockets />
<span className="sr-only">Strip {s + 1}</span>
</div>
))}
</div>
<div className="mt-4 flex items-center justify-between gap-3">
<p className="text-xs text-zinc-500 tabular-nums dark:text-zinc-400">
{picked.length} picked · {struck} struck
</p>
<div className="flex items-center gap-1.5">
<button
className="h-8 rounded-full px-3 font-medium text-xs text-zinc-600 outline-none transition-colors duration-150 hover:bg-zinc-100 focus-visible:ring-2 focus-visible:ring-zinc-400 disabled:opacity-40 dark:text-zinc-300 dark:hover:bg-zinc-800"
disabled={Object.keys(marks).length === 0}
onClick={() => {
setMarks({});
setExported(false);
}}
type="button"
>
Clear
</button>
<button
className={cn(
"flex h-8 items-center gap-1.5 rounded-full px-3.5 font-medium text-xs tabular-nums outline-none transition-colors duration-200 focus-visible:ring-2 focus-visible:ring-zinc-400 focus-visible:ring-offset-2 disabled:opacity-40 dark:focus-visible:ring-offset-zinc-900",
exported
? "bg-emerald-600 text-white dark:bg-emerald-500 dark:text-emerald-950"
: "bg-zinc-900 text-white hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-white"
)}
disabled={picked.length === 0}
onClick={() => {
onExport?.(picked);
setExported(true);
}}
type="button"
>
{exported && (
<Check aria-hidden className="size-3.5" strokeWidth={2.5} />
)}
{exported ? "Sent to edit" : `Export ${picked.length}`}
</button>
</div>
</div>
<AnimatePresence>
{lens && (
<motion.div
animate={{ opacity: 1 }}
aria-hidden="true"
className="pointer-events-none absolute z-20 rounded-full bg-zinc-900 bg-no-repeat shadow-[0_8px_24px_rgb(0_0_0/0.35),0_0_0_1px_rgb(255_255_255/0.5),0_0_0_4px_rgb(24_24_27/0.9)]"
exit={{ opacity: 0 }}
initial={{ opacity: 0 }}
style={{
width: LOUPE,
height: LOUPE,
left: lens.left - LOUPE / 2,
top: lens.top - LOUPE / 2,
backgroundImage: `url("${lens.frame.src}")`,
backgroundSize: lens.size,
backgroundPosition: lens.position,
}}
transition={{ duration: reduceMotion ? 0 : 0.12 }}
/>
)}
</AnimatePresence>
</div>
);
}