KQ-1563 · PETAL/GALLERY

Petal Gallery

Pictures sit as petals in an oval bloom around an empty heart, each clipped to a petal outline and kept upright inside it. Choosing one closes the bloom like a flower at dusk: the chosen picture flies from its petal into the heart on springs.glide, its outline morphing from petal to oval, while the other petals fold up toward you about their base hinges and over its rim on springs.drift — a wave running round from the chosen petal, swirled by `curl` and paced by `bloomSpeed` — as the frame dims and pushes in. The bloom is a listbox: arrow keys move round it, Home and End jump, Enter or Space choose, and Escape or a tap on a folded petal opens the bloom again.

KQ-1563 · PETAL/GALLERY

Fernworks journal · late summer

bloom open · 9 petals · choose one

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/petal-gallery

Props

items: PetalItem[]; default defaultPetalItems; The pictures; the first `petalCount` become petals: { src?, alt, caption?, art?, tint? }.
value / defaultValue: number | null; default null; The chosen picture, or null while the bloom is open; controlled or initial.
onValueChange: (index: number | null) => void; default —; Fires from the click, tap or key that chose a picture or opened the bloom.
petalCount: number; default 9; How many petals the bloom has, 5 to 12.
curl: number; default 0.5; How full the petals are, how much they cup at rest and how far the bloom swirls as it closes, 0 to 1.
bloomSpeed: number; default 1; Pace of the bloom closing and opening, 0.5 to 2; the springs' damping ratio is kept.
fold: number; default 108; How far the petals fold when the bloom closes, degrees; past 90 they lean over the picture.
dusk: number; default 0.35; How far the frame dims while the bloom is closed, 0 to 1.
perspective: number; default 1100; Distance of the eye from the bloom, px.
heartLabel: string; default "Choose a picture"; The words in the empty heart.
height: number; default 520; Height of the frame, px.
label: string; default "Pictures"; The bloom's accessible name.
disabled: boolean; default false; Stops choosing and opening.
className: string; default —; Classes for the outer frame.

Prop	Type	Default	Description
items	PetalItem[]	defaultPetalItems	The pictures; the first `petalCount` become petals: { src?, alt, caption?, art?, tint? }.
value / defaultValue	number \| null	null	The chosen picture, or null while the bloom is open; controlled or initial.
onValueChange	(index: number \| null) => void	—	Fires from the click, tap or key that chose a picture or opened the bloom.
petalCount	number	9	How many petals the bloom has, 5 to 12.
curl	number	0.5	How full the petals are, how much they cup at rest and how far the bloom swirls as it closes, 0 to 1.
bloomSpeed	number	1	Pace of the bloom closing and opening, 0.5 to 2; the springs' damping ratio is kept.
fold	number	108	How far the petals fold when the bloom closes, degrees; past 90 they lean over the picture.
dusk	number	0.35	How far the frame dims while the bloom is closed, 0 to 1.
perspective	number	1100	Distance of the eye from the bloom, px.
heartLabel	string	"Choose a picture"	The words in the empty heart.
height	number	520	Height of the frame, px.
label	string	"Pictures"	The bloom's accessible name.
disabled	boolean	false	Stops choosing and opening.
className	string	—	Classes for the outer frame.