Knob

The headless Knob of @audio-ui/react: its parts, what each renders and owns, and their props.


pnpm add @audio-ui/react

import { Knob } from "@audio-ui/react/knob";

Export	Kind	What it is
`Knob.Control`	function	The interactive surface: pointer drags (see `dragMode`), mouse-wheel stepping, and double tap (or Alt + click) to reset.
`Knob.Indicator`	function	The arc from `anchor` to the value, drawn over the `Track`.
`Knob.Label`	function	Accessible label, associated with the thumb's input.
`Knob.Mark`	function	A graduation on the dial at `value`, placed on the knob's scale: a layer the size of the knob, rotated to where `value` sits, so a tick drawn at its top lands on the sweep.
`Knob.Provider`	function	Sets how every `Knob.Root` below it turns by a drag, unless it has a `dragMode` of its own: wrap an app once to have all its knobs dragged up and down.
`Knob.Root`	function	Groups all parts of the knob and owns its value.
`Knob.Thumb`	function	Rotates with the value (`rotate`, clockwise from 12 o'clock), so a pointer drawn inside it points at the value.
`Knob.Track`	function	The full sweep of the dial, as an SVG arc.
`Knob.Value`	function	The formatted value (`format`/`locale` on Root).

Anatomy

Import the primitive and assemble its parts.

import { Knob } from "@audio-ui/react";

<Knob.Root>
  <Knob.Control>
    <Knob.Track />
    <Knob.Indicator />
    <Knob.Thumb />
    <Knob.Mark value={50} />
  </Knob.Control>
  <Knob.Value />
  <Knob.Label />
</Knob.Root>

API reference

Root

Groups all parts of the knob and owns its value. Dragging the Control, turning the mouse wheel over it, the keyboard on the Thumb's input, or a double tap (reset) all report through onValueChange / onValueCommitted. Renders a <div> element.

Props · 16

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Control

The interactive surface: pointer drags (see dragMode), mouse-wheel stepping, and double tap to reset. Sets touch-action: none so touch drags don't scroll the page. Renders a <div> element.

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Track

The full sweep of the dial, as an SVG arc. Renders a <svg> element.

Props · 1

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Indicator

The arc from anchor to the value, drawn over the Track. Renders a <svg> element.

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Thumb

Rotates with the value (rotate, clockwise from 12 o'clock), so a pointer drawn inside it points at the value. Holds the knob's native <input type="range">, which takes focus, carries the accessible name (aria-label / aria-labelledby) and the form value, and handles the keyboard. Renders a <div> element.

Props · 2

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Value

The formatted value (format/locale on Root). With editable, a double click, or Enter while it has focus, lets you type a value: Enter commits it (a unit or a decimal comma is fine, and it is clamped), Escape drops it, and it reports reason: "input-change". Renders a <output> element.

Props · 2

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Mark

A graduation on the dial at value, placed on the knob's scale: a layer the size of the knob, rotated to where value sits, so a tick drawn at its top lands on the sweep. Its --knob-mark-angle CSS variable is that rotation, to turn a label back upright. It carries data-active while the value has reached it from the anchor. Decorative: the input announces the value. Renders a <div> element.

Props · 1

Data attributes · 4

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

data-active

Whether the value has reached this mark from the anchor.

Label

Accessible label, associated with the thumb's input. Renders a <div> element.

Data attributes · 3

data-disabled

Present when disabled.

data-drag-mode

The dragMode: circular, revolution or vertical. Style the cursor from it.

data-dragging

Whether a pointer is dragging the knob.

Provider

Sets how every Knob.Root below it turns by a drag, unless the knob has a dragMode of its own: wrap an app once to have all its knobs dragged up and down. Renders no element.

Props · 1

Styled

The registry's styled Knob, its usage and interaction: Knob.

Headless styling Fader

Built by Ouest Labs, the source code is available on GitHub.

RSS