KQ-1600 · PLUMB/CURSOR

Plumb Cursor

A cursor effect bounded to its own box: a small brass plumb bob hangs from the pointer on a fine thread, a point mass under gravity on a thread that only pulls when taut, integrated at 240 Hz, so every movement swings it and it settles slowly to dead vertical — when a hairline drops from its tip to the floor — while fast circles pump it into an orbit round the pointer. A click pays out the reel and the bob falls freely to the end of its thread and bounces on the stretch before it is reeled back up on springs.glide; with no pointer it hangs from a nail, and the thread is handed to the pointer on springs.glide and carried back on springs.drift. Keyboard focus inside carries the thread over the focused control on springs.drift, and Enter drops it as a click does.

KQ-1600 · PLUMB/CURSOR

Gaugeworks · tools

Line 4 plumb set

Turned brass, a braided line, and a reel that pays out true.

on its nail · hold it over the card

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/plumb-cursor

Props

length: number; default 84; Thread length, px; kept to 70% of the box's height.
damping: number; default 0.3; How quickly a swing dies, 0 (it swings for ages) to 1 (it settles in one swing).
weight: number; default 1; The bob's weight, 0.5 to 2: a heavy bob is bigger, coasts longer against the air and stretches the thread further when it drops.
drop: number; default 0.6; How much thread a click pays out, as a share of the length, 0 to 1.5.
hold: number; default 900; How long the bob hangs at the end of its thread before it is reeled back, ms.
gravity: number; default 1; Gravity, as a multiple of the house value, 0.5 to 2: a slower or quicker swing.
color: string; default "var(--ink-2)"; The thread's colour.
bobColor: string; default "oklch(from var(--warn) 0.78 0.12 h)"; The bob's metal, a pigment that reads on both themes: brass from the warn token's hue, shaded into a turned body.
restAt: readonly [number, number]; default [0.9, 0.12]; Where the nail sits that the bob hangs from with no pointer, as fractions of the box.
plumbLine: boolean; default true; Drop a hairline to the floor when the bob hangs dead vertical.
followFocus: boolean; default true; Keyboard focus inside moves the thread over the focused control, and Enter or Space drops the bob.
touch: boolean; default true; On touch, the bob hangs from the finger while it is down and a quick tap drops it. Sets touch-action: none on the box.
disabled: boolean; default false; The bob stays on its nail.
onStateChange: (state: "resting" | "true" | "swinging" | "orbiting" | "dropped") => void; default —; What the bob is doing: on its nail, hanging true, swinging, orbiting the pointer, or dropped to the end of its thread.
children: React.ReactNode; default —; The content the bob hangs over; it stays fully interactive.
className: string; default —; Classes on the box the bob lives in; give it a size and, usually, overflow-clip and a radius.

Prop	Type	Default	Description
length	number	84	Thread length, px; kept to 70% of the box's height.
damping	number	0.3	How quickly a swing dies, 0 (it swings for ages) to 1 (it settles in one swing).
weight	number	1	The bob's weight, 0.5 to 2: a heavy bob is bigger, coasts longer against the air and stretches the thread further when it drops.
drop	number	0.6	How much thread a click pays out, as a share of the length, 0 to 1.5.
hold	number	900	How long the bob hangs at the end of its thread before it is reeled back, ms.
gravity	number	1	Gravity, as a multiple of the house value, 0.5 to 2: a slower or quicker swing.
color	string	"var(--ink-2)"	The thread's colour.
bobColor	string	"oklch(from var(--warn) 0.78 0.12 h)"	The bob's metal, a pigment that reads on both themes: brass from the warn token's hue, shaded into a turned body.
restAt	readonly [number, number]	[0.9, 0.12]	Where the nail sits that the bob hangs from with no pointer, as fractions of the box.
plumbLine	boolean	true	Drop a hairline to the floor when the bob hangs dead vertical.
followFocus	boolean	true	Keyboard focus inside moves the thread over the focused control, and Enter or Space drops the bob.
touch	boolean	true	On touch, the bob hangs from the finger while it is down and a quick tap drops it. Sets touch-action: none on the box.
disabled	boolean	false	The bob stays on its nail.
onStateChange	(state: "resting" \| "true" \| "swinging" \| "orbiting" \| "dropped") => void	—	What the bob is doing: on its nail, hanging true, swinging, orbiting the pointer, or dropped to the end of its thread.
children	React.ReactNode	—	The content the bob hangs over; it stays fully interactive.
className	string	—	Classes on the box the bob lives in; give it a size and, usually, overflow-clip and a radius.