KQ-1243 · KOI/POND

Koi Pond

A background that is a garden pond seen from above, koi gliding in loose schools under a gently rippling surface while lily pads drift on it, with your content on top; the pointer is a hand over the water, whose shadow makes nearby koi edge away and whose stillness draws the bolder ones back to mill around it. A touch spreads a ring and scatters every koi within reach: they steer away at up to seven radians a second with a burst of speed, glide as the fright fades over a second and a half, then return; the koi steer rather than spring, each body rebuilt every frame from a spine that follows its head, and under reduced motion the scatter is a cross-fade on the base duration. A transparent button behind the content is the keyboard's way in: arrow keys move the hand and Space or Enter touches the water.

KQ-1243 · KOI/POND

Basinworks Tea Garden

The pond is open until dusk

Benches by the water, 9 to 6

7 koi · the pond is calm

Open it on the Atelier stage

Install

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

$ pnpm dlx shadcn@latest add @kinetiq/koi-pond

Props

children: ReactNode; default —; The content on top of the water, in its own layer that fills the box: a hero, a heading, a call to action.
fish: number; default 7; How many koi live in the pond, 3 to 12; changing it adds or removes koi without disturbing the others.
ripple: number; default 0.5; How alive the surface is, 0 to 1: the glints, the rings, the shimmer over the koi and the pads' bob. At 0 the water is glass.
water: "jade" | "ink" | "dusk"; default "jade"; The pond's water, pigments mixed a little into the page so the pond sits in its theme.
label: string; default "Koi pond"; The accessible name of the pond's keyboard surface.
onScatter: (count: number) => void; default —; A touch on the water scattered this many koi, reported from the press or key that touched it.
disabled: boolean; default false; The koi swim on; the hand is ignored and touch scrolling is left to the page.
className: string; default —; Sizes the box; the default is h-full w-full, so it fills its container.

Prop	Type	Default	Description
children	ReactNode	—	The content on top of the water, in its own layer that fills the box: a hero, a heading, a call to action.
fish	number	7	How many koi live in the pond, 3 to 12; changing it adds or removes koi without disturbing the others.
ripple	number	0.5	How alive the surface is, 0 to 1: the glints, the rings, the shimmer over the koi and the pads' bob. At 0 the water is glass.
water	"jade" \| "ink" \| "dusk"	"jade"	The pond's water, pigments mixed a little into the page so the pond sits in its theme.
label	string	"Koi pond"	The accessible name of the pond's keyboard surface.
onScatter	(count: number) => void	—	A touch on the water scattered this many koi, reported from the press or key that touched it.
disabled	boolean	false	The koi swim on; the hand is ignored and touch scrolling is left to the page.
className	string	—	Sizes the box; the default is h-full w-full, so it fills its container.