KQ-1842 · BUOY/TAGS

Buoy Tags

A tag picker floating on water: pill-shaped toggle buttons moored on slack lines ride a gently moving surface, a slow swell lifting and rocking one float after another while a small heightfield carries every ripple. The pointer makes a current, so the tags drift toward you within the slack of their moorings and bump softly into each other as capsules that trade momentum and spin, then drift home. Pressing a tag dunks it under the water and it comes back up on springs.recoil inside a splash ring that rocks its neighbours, selected or cleared; tags are real buttons in reading order, Enter and Space dunk them, and keyboard focus pulls the current to the focused tag.

KQ-1842 · BUOY/TAGS

Basinworks journal

What would you like to read about?

2 topics · tides, kelp

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/buoy-tags

Props

tags: BuoyTag[]; default defaultBuoyTags; The tags on the water: { id, label, color? }.
value / defaultValue: string[]; default []; The ids of the selected tags; controlled or initial.
onValueChange: (ids: string[]) => void; default —; Fires from the press or key that dunked a tag, with the new selection.
multiple: boolean; default true; Several tags may be selected; off, choosing one clears the rest.
bob: number; default 0.5; How high the swell runs, 0 (flat calm) to 1: how much the tags bob and rock.
drift: number; default 0.5; How strongly the hand's current pulls the tags and how much slack their moorings give, 0 to 1.
depth: number; default 0.5; How deep the water is, 0 to 1: its colour, the length of the moorings, how far shadows fall and how long the swell runs.
moorings: boolean; default true; Draw each tag's mooring line down into the water.
splash: number; default 0.7; How big a dunk's splash is, 0 to 1: the rings and the waves that rock the neighbours.
interactive: boolean; default true; The hand (pointer or keyboard focus) makes a current the tags drift on.
paused: boolean; default false; Hold the water and the tags still.
seed: number; default 1; Seeds the swell and the moorings.
dpr: number; default 2; Cap on the canvas's device pixel ratio, at most 2.
sound: boolean; default false; Play the plips of a dunk. Off unless asked for.
label: string; default "Tags"; The group's accessible name.
onDunk: (id: string) => void; default —; Fires when a tag is dunked, with its id.
disabled: boolean; default false; No presses; the water lies still.
className: string; default "h-56 w-full"; Sizes the water.

Prop	Type	Default	Description
tags	BuoyTag[]	defaultBuoyTags	The tags on the water: { id, label, color? }.
value / defaultValue	string[]	[]	The ids of the selected tags; controlled or initial.
onValueChange	(ids: string[]) => void	—	Fires from the press or key that dunked a tag, with the new selection.
multiple	boolean	true	Several tags may be selected; off, choosing one clears the rest.
bob	number	0.5	How high the swell runs, 0 (flat calm) to 1: how much the tags bob and rock.
drift	number	0.5	How strongly the hand's current pulls the tags and how much slack their moorings give, 0 to 1.
depth	number	0.5	How deep the water is, 0 to 1: its colour, the length of the moorings, how far shadows fall and how long the swell runs.
moorings	boolean	true	Draw each tag's mooring line down into the water.
splash	number	0.7	How big a dunk's splash is, 0 to 1: the rings and the waves that rock the neighbours.
interactive	boolean	true	The hand (pointer or keyboard focus) makes a current the tags drift on.
paused	boolean	false	Hold the water and the tags still.
seed	number	1	Seeds the swell and the moorings.
dpr	number	2	Cap on the canvas's device pixel ratio, at most 2.
sound	boolean	false	Play the plips of a dunk. Off unless asked for.
label	string	"Tags"	The group's accessible name.
onDunk	(id: string) => void	—	Fires when a tag is dunked, with its id.
disabled	boolean	false	No presses; the water lies still.
className	string	"h-56 w-full"	Sizes the water.