KQ-1628 · DROPLET/SWAP

Droplet Swap

A gallery whose transition is a drop of water. A drop rolls across the picture with the next one inside it, small and upside down as a ball lens shows it, its view sliding the other way as it moves, with a dark meniscus, a highlight, a cast shadow and a caustic, squashing along its path with speed and leaving a wet trail that dries. It gathers as it rolls, and at full size it bursts into a spreading circle of the new picture, upright, on the springs.glide constants, throwing a few splash beads and leaving a sheen that dries. Drag to steer: a drop forms under the finger and follows it 1:1, carrying the next picture right or the previous one left, and a flick rolls it on by projection. Arrow keys roll next and previous, Home and End roll to the ends, and dots choose a picture.

KQ-1628 · DROPLET/SWAP

Coldbrook Travel · winter

Five coasts this winter

1 of 5 · Coldbrook harbour, dawn · drag a drop or press →

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/droplet-swap

Props

items: readonly DropletSwapItem[]; default defaultDropletSwapItems; The pictures, in order: { src?, alt, caption? }. Items without src get a drawn scene.
value / defaultValue: number; default 0; The index of the picture shown, controlled or initial.
onValueChange: (index: number) => void; default —; Fires when a drop has burst and a new picture fills the frame, with its index.
dropSize: number; default 0.45; How big the drop has grown when it bursts: its diameter as a share of the frame's height, 0.2 to 0.6.
rollSpeed: number; default 420; How fast a drop rolls across, in px/s.
refraction: number; default 0.6; The lens's power, 0 (most of the picture, a faint rim) to 1 (a close-up of its middle, a dark meniscus and a bright caustic).
trail: boolean; default true; Leave a wet trail behind the drop that dries.
splash: boolean; default true; Throw a few small drops when it bursts.
interval: number; default 0; ms between automatic swaps, 0 for none. Held while hovered, focused, hidden or off screen.
loop: boolean; default true; Wrap from the last picture to the first and back.
indicators: boolean; default true; Show a dot per picture to choose it.
captions: boolean; default true; Show the caption over the picture's foot.
label: string; default "Gallery"; Names the gallery for assistive technology.
sound: boolean; default false; A plip when a drop forms under the finger and a blup when it bursts, only for the visitor's own drag, tap or key.
disabled: boolean; default false; Shows the picture and takes no input.
className: string; default "h-56 w-full"; Sizes the frame.

Prop	Type	Default	Description
items	readonly DropletSwapItem[]	defaultDropletSwapItems	The pictures, in order: { src?, alt, caption? }. Items without src get a drawn scene.
value / defaultValue	number	0	The index of the picture shown, controlled or initial.
onValueChange	(index: number) => void	—	Fires when a drop has burst and a new picture fills the frame, with its index.
dropSize	number	0.45	How big the drop has grown when it bursts: its diameter as a share of the frame's height, 0.2 to 0.6.
rollSpeed	number	420	How fast a drop rolls across, in px/s.
refraction	number	0.6	The lens's power, 0 (most of the picture, a faint rim) to 1 (a close-up of its middle, a dark meniscus and a bright caustic).
trail	boolean	true	Leave a wet trail behind the drop that dries.
splash	boolean	true	Throw a few small drops when it bursts.
interval	number	0	ms between automatic swaps, 0 for none. Held while hovered, focused, hidden or off screen.
loop	boolean	true	Wrap from the last picture to the first and back.
indicators	boolean	true	Show a dot per picture to choose it.
captions	boolean	true	Show the caption over the picture's foot.
label	string	"Gallery"	Names the gallery for assistive technology.
sound	boolean	false	A plip when a drop forms under the finger and a blup when it bursts, only for the visitor's own drag, tap or key.
disabled	boolean	false	Shows the picture and takes no input.
className	string	"h-56 w-full"	Sizes the frame.