KQ-1112 · SNAP/GUIDES

Snap Guides

A small design canvas whose layers line themselves up: drag one and, within a few pixels, its edges and centre are pulled onto the edges and centres of the other layers and the artboard on a quick critically damped spring (the flick), with a guide drawn across both objects, a tick, and live labels measuring the gap to the nearest neighbour on each side. The layer is 1:1 under the finger when nothing pulls it, rubber-bands past the artboard's edge and glides back in carrying its release velocity. Arrow keys nudge the focused layer by 1 and Shift+Arrow by 10, with the same snapping and the same tick.

KQ-1112 · SNAP/GUIDES

4 layers · drag one, or tab to it and use the arrows

Open it on the Tactile stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/snap-guides

Props

layers: SnapGuidesLayer[]; default —; The layers, in paint order: id, label (the accessible name), width and height in artboard px, and content, which scales with the artboard and never takes pointer events.
value / defaultValue: Record<string, { x: number; y: number }>; default {}; Where each layer sits, by id, in artboard px from the top-left corner. Controlled or uncontrolled; a layer with no entry starts at 0, 0.
onValueChange: (value: SnapGuidesValue, change: { id: string; x: number; y: number; alignedWith: string[] }) => void; default —; Fires from the release or the key that moved a layer, with every position and the labels of the layers the moved one now lines up with. A controlled layer waits for the host: a refused move glides back.
boardWidth: number; default 400; The artboard's width in artboard px. The artboard keeps its aspect ratio and scales to fit its box.
boardHeight: number; default 200; The artboard's height in artboard px.
label: string; default "Artboard"; The artboard's accessible name.
snap: number; default 6; How close, in artboard px, a line must come before it pulls the layer into line, 2 to 16.
guides: "edges" | "centres" | "both"; default "both"; Which lines snap and draw guides: left, right, top and bottom edges, the centres, or all of them.
distances: boolean; default true; Live measurement lines and labels from the moving layer to its nearest neighbour, or the artboard edge, on each side.
grid: boolean; default false; Shows an 8 px grid and, when no alignment is in reach, snaps the layer's corner to it, so it steps along the grid.
sound: boolean; default false; Tick when an edge finds another: higher for centres, lower for the artboard, softest for grid steps. Nothing plays, and no audio context exists, unless this is on.
disabled: boolean; default false; Dims the artboard and stops every drag and nudge.
className: string; default —; Merged onto the artboard's classes.

Prop	Type	Default	Description
layers	SnapGuidesLayer[]	—	The layers, in paint order: id, label (the accessible name), width and height in artboard px, and content, which scales with the artboard and never takes pointer events.
value / defaultValue	Record<string, { x: number; y: number }>	{}	Where each layer sits, by id, in artboard px from the top-left corner. Controlled or uncontrolled; a layer with no entry starts at 0, 0.
onValueChange	(value: SnapGuidesValue, change: { id: string; x: number; y: number; alignedWith: string[] }) => void	—	Fires from the release or the key that moved a layer, with every position and the labels of the layers the moved one now lines up with. A controlled layer waits for the host: a refused move glides back.
boardWidth	number	400	The artboard's width in artboard px. The artboard keeps its aspect ratio and scales to fit its box.
boardHeight	number	200	The artboard's height in artboard px.
label	string	"Artboard"	The artboard's accessible name.
snap	number	6	How close, in artboard px, a line must come before it pulls the layer into line, 2 to 16.
guides	"edges" \| "centres" \| "both"	"both"	Which lines snap and draw guides: left, right, top and bottom edges, the centres, or all of them.
distances	boolean	true	Live measurement lines and labels from the moving layer to its nearest neighbour, or the artboard edge, on each side.
grid	boolean	false	Shows an 8 px grid and, when no alignment is in reach, snaps the layer's corner to it, so it steps along the grid.
sound	boolean	false	Tick when an edge finds another: higher for centres, lower for the artboard, softest for grid steps. Nothing plays, and no audio context exists, unless this is on.
disabled	boolean	false	Dims the artboard and stops every drag and nudge.
className	string	—	Merged onto the artboard's classes.