KQ-1146 · THUMB/WHEEL

Thumb Wheel

A value set by rolling a knurled wheel seen edge-on in a slot: the knurl scrolls 1:1 under the finger, its ridges bunching toward the top and bottom as the cylinder turns away, while the value sits beside it level with a fixed notch and a gauge shows where the wheel is between its stops. Rolled past a stop it rubber-bands; flicked, its landing is projected at a rate set by friction, snapped to a step when detents are on, and reached on a critically damped spring with that time constant, so it slows exponentially and stops on the step, while a throw past a stop hits it on the snap spring. Arrows step, PageUp and PageDown move ten steps and Home and End go to the stops, rolling the wheel there through the same fine ratchet; the scroll wheel rolls it as it would scroll content.

KQ-1146 · THUMB/WHEEL

Desk lamp

Fernworks studio, bench 2

Brightness

brightness 60% · roll, flick or scroll

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/thumb-wheel

Props

value / defaultValue: number; default min; The value the wheel is set to. Controlled or uncontrolled; a value the host refuses rolls back.
onValueChange: (value: number) => void; default —; Fires from the roll, flick, scroll, tap or key that changed it: per step while rolling, and once with the value it lands on.
min: number; default 0; The bottom stop.
max: number; default 100; The top stop.
step: number; default 1; One detent's worth of value, and what a key or a tap moves it by.
label: string; default —; What the wheel sets: the slider's accessible name, shown over the value.
unit: string; default —; Printed after the value and read in its value text, as in "%" or "dB".
knurl: "fine" | "coarse" | "diamond"; default "fine"; The pattern cut in the wheel's edge: fine straight ridges, coarse ones twice as far apart, or a diamond crosshatch drawn as the two helices a real knurl leaves.
friction: number; default 0.4; How soon a flicked wheel stops, 0 to 1: at 0 it coasts a long way, at 1 it stops almost at once.
detents: boolean; default true; Click and settle on whole steps. Off, the wheel rolls freely and stops wherever it coasts, and the value shows one more decimal; keys and taps still land on whole steps.
range: number; default 1.5; How far the wheel turns from one stop to the other, in turns, 0.5 to 3: short is quick and coarse, long is slow and fine. The gauge shows one mark per quarter turn.
sound: boolean; default false; A fine ratchet tick per step as the wheel rolls (per ridge, softer, with detents off), rising with the value, and a clack when it meets a stop. Nothing plays, and no audio context exists, unless this is on.
disabled: boolean; default false; Dims the wheel, takes it out of the tab order and ignores drags, scrolls and keys.
className: string; default —; Merged onto the root's classes.

Prop	Type	Default	Description
value / defaultValue	number	min	The value the wheel is set to. Controlled or uncontrolled; a value the host refuses rolls back.
onValueChange	(value: number) => void	—	Fires from the roll, flick, scroll, tap or key that changed it: per step while rolling, and once with the value it lands on.
min	number	0	The bottom stop.
max	number	100	The top stop.
step	number	1	One detent's worth of value, and what a key or a tap moves it by.
label	string	—	What the wheel sets: the slider's accessible name, shown over the value.
unit	string	—	Printed after the value and read in its value text, as in "%" or "dB".
knurl	"fine" \| "coarse" \| "diamond"	"fine"	The pattern cut in the wheel's edge: fine straight ridges, coarse ones twice as far apart, or a diamond crosshatch drawn as the two helices a real knurl leaves.
friction	number	0.4	How soon a flicked wheel stops, 0 to 1: at 0 it coasts a long way, at 1 it stops almost at once.
detents	boolean	true	Click and settle on whole steps. Off, the wheel rolls freely and stops wherever it coasts, and the value shows one more decimal; keys and taps still land on whole steps.
range	number	1.5	How far the wheel turns from one stop to the other, in turns, 0.5 to 3: short is quick and coarse, long is slow and fine. The gauge shows one mark per quarter turn.
sound	boolean	false	A fine ratchet tick per step as the wheel rolls (per ridge, softer, with detents off), rising with the value, and a clack when it meets a stop. Nothing plays, and no audio context exists, unless this is on.
disabled	boolean	false	Dims the wheel, takes it out of the tab order and ignores drags, scrolls and keys.
className	string	—	Merged onto the root's classes.