KQ-1591 · AVATAR/JAR

Avatar Jar

A glass jar of avatar pebbles that are real rigid discs: they pour in through the neck one by one, tumble, roll on each other and settle under gravity with a rattle. Drag the jar sideways and it turns 1:1 under the finger, rubber-banded past `tilt`, the turning frame sloshing the heap against the low side; on release the throw is projected and the jar glides to rest with the release velocity. Clicking a pebble lifts it out on the snap spring, upright and enlarged with its name card settling beside it on flick, and the heap closes the gap; clicking again drops it back through the mouth on glide to find a gap. Up and Down move between pebbles, Left and Right tilt, Enter lifts or drops, Escape drops.

KQ-1591 · AVATAR/JAR

Fieldline · Design team

16 people

upright · drag to tilt, click a face

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/avatar-jar

Props

items: readonly AvatarJarItem[]; default defaultAvatarJarItems; What is in the jar: { id, name, role?, src?, color? }. More than fit are counted on the lid.
angle / defaultAngle: number; default 0; The jar's tilt in degrees; negative leans left.
onAngleChange: (angle: number) => void; default —; Fires when a drag or a key leaves the jar at a new tilt, with the angle it will rest at.
lifted / defaultLifted: string | null; default null; The id of the pebble lifted out of the jar.
onLiftedChange: (id: string | null) => void; default —; Fires when a pebble is lifted out (its id) or dropped back (null).
tilt: number; default 28; How far the jar can tip either way, in degrees.
pebbleSize: number; default 34; A pebble's diameter in jar units (the jar is 200 wide inside).
glass: "clear" | "sea" | "amber" | "smoke"; default "clear"; The glass's tint.
gravity: number; default 1; Gravity as a multiple of the house's.
bounce: number; default 0.28; How much a pebble bounces off glass and other pebbles, 0 to 0.8.
pour: "inView" | "mount" | "none"; default "inView"; When the pebbles pour in; with none they start in a heap.
repourKey: number; default 0; Change it to pour every pebble in again from the top.
label: string; default "Jar"; Names the jar for assistive technology.
sound: boolean; default false; Clack when pebbles the visitor moved hit the glass and each other.
seed: number; default 7; Seeds where pebbles start and how each portrait is drawn.
paused: boolean; default false; Freeze the pebbles where they are.
disabled: boolean; default false; Shows the jar but takes no input.
className: string; default "h-[30rem] w-full"; Sizes the jar's box; give it a height.

Prop	Type	Default	Description
items	readonly AvatarJarItem[]	defaultAvatarJarItems	What is in the jar: { id, name, role?, src?, color? }. More than fit are counted on the lid.
angle / defaultAngle	number	0	The jar's tilt in degrees; negative leans left.
onAngleChange	(angle: number) => void	—	Fires when a drag or a key leaves the jar at a new tilt, with the angle it will rest at.
lifted / defaultLifted	string \| null	null	The id of the pebble lifted out of the jar.
onLiftedChange	(id: string \| null) => void	—	Fires when a pebble is lifted out (its id) or dropped back (null).
tilt	number	28	How far the jar can tip either way, in degrees.
pebbleSize	number	34	A pebble's diameter in jar units (the jar is 200 wide inside).
glass	"clear" \| "sea" \| "amber" \| "smoke"	"clear"	The glass's tint.
gravity	number	1	Gravity as a multiple of the house's.
bounce	number	0.28	How much a pebble bounces off glass and other pebbles, 0 to 0.8.
pour	"inView" \| "mount" \| "none"	"inView"	When the pebbles pour in; with none they start in a heap.
repourKey	number	0	Change it to pour every pebble in again from the top.
label	string	"Jar"	Names the jar for assistive technology.
sound	boolean	false	Clack when pebbles the visitor moved hit the glass and each other.
seed	number	7	Seeds where pebbles start and how each portrait is drawn.
paused	boolean	false	Freeze the pebbles where they are.
disabled	boolean	false	Shows the jar but takes no input.
className	string	"h-[30rem] w-full"	Sizes the jar's box; give it a height.