KQ-1799 · WILLOW/SHELL

Willow Shell

A firework display in one tall frame: a night sky over a far riverbank, the river below mirroring it in rippling strips. A click fires a shell from the bank on a real ballistic arc, shedding sparks, and at its apex it bursts with a flash that lifts the sky toward its colour: a willow hangs heavy stars whose strands droop with age and cool from white-gold to amber as they fade, a peony blooms round and twinkles out, and crossette comets split in a cross mid-flight, while smoke drifts on the wind and catches later flashes. The frame is a button: Left and Right move the aim mark along the bank on springs.snap and Enter or Space launches there; a scripted `sequence` plays a finale.

KQ-1799 · WILLOW/SHELL

Waylight Riverside · Sat 21:30

Fireworks over the water

Click the sky, or aim with the arrow keys.

willow · 0 shells burst over the river

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/willow-shell

Props

children: React.ReactNode; default —; A headline over the sky; it takes no pointer input. The root sets --willow-ink and --willow-faint for text on the night.
shell: "willow" | "peony" | "crossette" | "mixed"; default "willow"; The burst: hanging gold willow, a round peony, crossettes that split in a cross, or each in turn.
spread: number; default 0.55; How wide the burst opens, 0 to 1; wider shells carry more stars.
gravity: number; default 0.5; How hard stars and strands droop, 0 (they hang) to 1 (they fall).
height: number; default 0.6; How high a shell bursts, 0 (just over the bank) to 1 (the top of the sky).
stars: number; default 72; Stars per shell, 24 to 140.
trail: number; default 0.6; How long willow strands and star streaks are, 0 to 1.
gold: string; default "oklch(from var(--warn) 0.86 0.12 h)"; The willow's gold, any CSS colour.
colors: string[]; default —; Star colours for peonies and crossettes; defaults to four token pigments.
wind: number; default 0.2; Wind across the river, -1 to 1: carries smoke and strands.
reflection: boolean; default true; Mirror the sky in a river under the bank.
sequence: WillowCue[]; default defaultWillowFinale; The scripted show `playing` runs: each cue's time in ms, shell, place along the bank, height and size.
playing / defaultPlaying: boolean; default false; Whether the show is running, controlled or initial. Turning it on starts the show from its first cue.
onPlayingChange: (playing: boolean) => void; default —; Fires with false when the show's last shell has faded.
trigger: "manual" | "inView" | "mount"; default "manual"; What launches an opening shell by itself: coming into view, mounting, or nothing but the visitor.
onBurst: (shell: "willow" | "peony" | "crossette", x: number) => void; default —; Fires as each shell bursts, with its type and where along the bank it was fired.
paused: boolean; default false; Hold everything in the air where it is and take no launches.
seed: number; default 7; Seeds the stars, the bank and every burst.
dpr: number; default 2; Cap on the canvas's device pixel ratio, at most 2.
label: string; default "Fireworks over the river"; The frame's accessible name.
sound: boolean; default false; Play the whistle as a shell leaves and the flare as it bursts, only for the visitor's own launches (and a show the visitor just started).
disabled: boolean; default false; Shows the sky but takes no launches.
className: string; default "h-96 w-full"; Sizes the frame.

Prop	Type	Default	Description
children	React.ReactNode	—	A headline over the sky; it takes no pointer input. The root sets --willow-ink and --willow-faint for text on the night.
shell	"willow" \| "peony" \| "crossette" \| "mixed"	"willow"	The burst: hanging gold willow, a round peony, crossettes that split in a cross, or each in turn.
spread	number	0.55	How wide the burst opens, 0 to 1; wider shells carry more stars.
gravity	number	0.5	How hard stars and strands droop, 0 (they hang) to 1 (they fall).
height	number	0.6	How high a shell bursts, 0 (just over the bank) to 1 (the top of the sky).
stars	number	72	Stars per shell, 24 to 140.
trail	number	0.6	How long willow strands and star streaks are, 0 to 1.
gold	string	"oklch(from var(--warn) 0.86 0.12 h)"	The willow's gold, any CSS colour.
colors	string[]	—	Star colours for peonies and crossettes; defaults to four token pigments.
wind	number	0.2	Wind across the river, -1 to 1: carries smoke and strands.
reflection	boolean	true	Mirror the sky in a river under the bank.
sequence	WillowCue[]	defaultWillowFinale	The scripted show `playing` runs: each cue's time in ms, shell, place along the bank, height and size.
playing / defaultPlaying	boolean	false	Whether the show is running, controlled or initial. Turning it on starts the show from its first cue.
onPlayingChange	(playing: boolean) => void	—	Fires with false when the show's last shell has faded.
trigger	"manual" \| "inView" \| "mount"	"manual"	What launches an opening shell by itself: coming into view, mounting, or nothing but the visitor.
onBurst	(shell: "willow" \| "peony" \| "crossette", x: number) => void	—	Fires as each shell bursts, with its type and where along the bank it was fired.
paused	boolean	false	Hold everything in the air where it is and take no launches.
seed	number	7	Seeds the stars, the bank and every burst.
dpr	number	2	Cap on the canvas's device pixel ratio, at most 2.
label	string	"Fireworks over the river"	The frame's accessible name.
sound	boolean	false	Play the whistle as a shell leaves and the flare as it bursts, only for the visitor's own launches (and a show the visitor just started).
disabled	boolean	false	Shows the sky but takes no launches.
className	string	"h-96 w-full"	Sizes the frame.