Overview

Components

Audio Player

Libs

Resources

Knob

Rotary control for parameters - drag, wheel, keyboard, optional fader-style vertical pan, and reset via double-tap.

Rotary knob for continuous parameters (level, cutoff, pan, etc.). The registry component wraps Knob primitives from @audio-ui/react with size variants and theme styles; behavior and geometry are documented below.

Overview

Interaction model: Circular drag by default, optional vertical “fader” pan, mouse wheel, keyboard nudging, and double-tap / double-click to snap back to defaultValue.
Feedback: Track rail, highlighted arc between anchor and value when useful, and a needle aligned to the current value.
Accessibility: The draggable surface is a role="slider" with aria-valuenow / min / max; label via aria-label or aria-labelledby.

Installation

pnpm dlx shadcn@latest add @audio/knob

Usage

import { Knob } from "@/components/audio/knob";

Uncontrolled - initial value only:

<Knob defaultValue={50} max={100} min={0} step={1} />

Controlled - drive the value from state (typical in audio UIs):

const [cutoff, setCutoff] = useState(1000);
 
<Knob
  max={20_000}
  min={20}
  onValueChange={setCutoff}
  step={1}
  value={cutoff}
/>

Pass defaultValue even when controlled if you use double-tap reset; it defines the value the knob jumps back to (still clamped and stepped).

Interaction

Pointer

Behavior	Details
Circular drag (default)	Value tracks accumulated rotation around the center from the value at pointer down. Uses `dragSensitivity` to choose the angular reference (see Pointer mapping).
Vertical fader drag	Set `dragOptions={{ verticalPanEnabled: true }}`. After a small movement threshold, a mostly-vertical drag nudges the value like a fader; circular drag still works when the gesture is more rotational.
Double-tap / double-click	Two quick releases with ≤ ~12px movement from each pointer down, within ~320ms, resets to `defaultValue`, or to the midpoint of `min…max` if `defaultValue` is omitted. Fires `onValueCommit` like a normal commit.

Default geometry uses a large sweep (~288° from angleGapRad), so arc and revolution can feel similar; use a smaller angleRange if you want arc to span the full range in less than one physical turn. Values always clamp to min…max (no wrap).

Keyboard

Focused knob:

Key	Action
`ArrowUp` / `ArrowRight`	Increase by `step`
`ArrowDown` / `ArrowLeft`	Decrease by `step`
`PageUp`	Increase by `step × 10`
`PageDown`	Decrease by `step × 10`
`Home`	`min`
`End`	`max`

Prop	Type	Default	Description
`value`	`number`	-	Controlled value.
`defaultValue`	`number`	-	Uncontrolled starting value; also the double-tap reset target when provided.
`min`	`number`	`0`	Minimum.
`max`	`number`	`100`	Maximum.
`step`	`number`	`1`	Quantization step (drag, wheel, keyboard, reset).
`disabled`	`boolean`	`false`	Disables pointer, wheel, and keyboard.
`onValueChange`	`(value: number) => void`	-	Live updates while dragging or adjusting.
`onValueCommit`	`(value: number) => void`	-	When the gesture ends (pointer up, wheel tick, reset, etc.).
`aria-label`	`string`	-	Accessible name for the slider.
`aria-labelledby`	`string`	-	ID of a labeling element.

Size and rail

Prop	Type	Default	Description
`size`	`"sm" \| "default" \| "lg" \| "xl"`	`"default"`	Diameter variant.
`className`	`string`	-	On the root wrapper.
`arcRadius`	`number`	`23`	Arc radius in the 48×48 viewBox.
`arcStrokeWidth`	`number`	`3`	Track / arc stroke width.
`angleGapRad`	`number`	`π/5`	Bottom gap in radians; drives default `angleOffset` / `angleRange`.
`angleOffset`	`number`	from gap	Dial start angle in degrees (optional override).
`angleRange`	`number`	from gap	Total sweep in degrees (optional override).
`anchor`	`number`	-	Secondary value for the highlighted arc segment.
`indicatorSpan`	`[number, number]`	`[0.24, 0.58]`	Needle inner / outer radius as fractions of track radius.
`indicatorWidth`	`number`	`2.75`	Needle stroke width.

Pointer and drag

Prop	Type	Default	Description
`dragSensitivity`	`"arc" \| "revolution"`	`"arc"`	`arc`: one full span matches `angleRange` (as radians). `revolution`: one full span matches 360° of pointer travel. Both are relative to the value at pointer down and clamp to `min…max`.
`dragOptions`	see below	-	Pan vs rotate, dead zone, vertical sensitivity.

`dragOptions` (`Knob.DragOptions`)

Field	Default	Purpose
`verticalPanEnabled`	`false`	Allow vertical fader-style drag when `true`.
`panSensitivityDivisor`	`150`	Vertical pan scale: `(max - min) / divisor` per unit delta.
`centerDeadZoneRel` / `centerDeadZoneMinPx`	`0.08` / `2`	Hub radius where angle follows pointer without accumulating huge jumps.
`modeLockMinPx` / `modeLockRel`	`6` / `0.055`	Movement before locking rotate vs pan mode.
`panMinVerticalPx`	`10`	Minimum vertical movement to consider pan.
`panDominanceRatio`	`2.5`	Pan wins when `movedY > movedX × ratio`.

Additional HTML attributes on the root are forwarded where valid.

With anchor range

Pointer mapping

Each preview shows one mapping in isolation (live value under the control).

Default arc (circular)

Vertical fader-style drag

Gain

50%

Reverb

50%

Delay

50%

Drive

50%

Last updated 4/15/2026

Fader Transport

Knob

Overview

Installation

Usage

Interaction

Pointer

Keyboard

Wheel

API reference

Value and state

Size and rail

Pointer and drag

`dragOptions` (`Knob.DragOptions`)

Examples

Disabled state

Size variants

Rail, anchor, and range highlight

Pointer mapping

Default arc (circular)

Vertical fader-style drag

Revolution (360° reference)

Reset with double-tap

Fine step precision (`step={0.01}`)

Live value vs committed value callbacks

Filter cutoff

Channel strip

Knob

dragOptions (Knob.DragOptions)

Default arc (circular)

Vertical fader-style drag

Revolution (360° reference)

`dragOptions` (`Knob.DragOptions`)