{"name" in current ? current.name : current.label}
{current.format(values[current.id])}
Filter
{filter.map((p) => (
setActive(p.id)}
/>
))}
Amp envelope
{envelope.map((p) => (
setActive(p.id)}
/>
))}
);
}
```
### Detents and steps
Detents catch the cap while you drag or scroll, with a small spring as it lands. A knob with a dozen steps or fewer prints a mark at each one; arc narrows the sweep.
```tsx
"use client";
import { Knob } from "@/components/ui/knob";
const pan = (v: number) => (v === 0 ? "Center" : v < 0 ? `${-v} L` : `${v} R`);
const semitones = (v: number) => (v === 0 ? "0 st" : `${v > 0 ? "+" : "−"}${Math.abs(v)} st`);
const octaves = ["32′", "16′", "8′", "4′", "2′"];
export default function KnobDetents() {
return (
octaves[i]}
showValue
/>
);
}
```
### In a form
Each knob with a name submits its value through a hidden input. Double-click returns a knob to its defaultValue.
```tsx
"use client";
import * as React from "react";
import { Button } from "@/components/ui/button";
import { Knob } from "@/components/ui/knob";
const db = (v: number) => `${v > 0 ? "+" : v < 0 ? "−" : ""}${Math.abs(v)} dB`;
export default function KnobForm() {
const [saved, setSaved] = React.useState(null);
return (
);
}
```
### Sizes, colors and disabled
Three sizes share one drawing. Disabled knobs go dark and leave the tab order.
```tsx
"use client";
import { Knob } from "@/components/ui/knob";
export default function KnobSizes() {
return (
`${v}%`} showValue />
);
}
```
## API reference
### Knob
className and style go on the outer element. The ref and every other div attribute go on the dial, which has role="slider".
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | Controlled value. |
| `defaultValue` | `number` | `min` | Initial value when uncontrolled, and where a double-click returns to. |
| `onValueChange` | `(value: number) => void` | — | Called on every change while dragging, scrolling or pressing keys. |
| `onValueCommit` | `(value: number) => void` | — | Called once a drag, key press or scroll gesture ends. |
| `min` | `number` | `0` | Lowest value. When min is below zero and max above it, the ring lights outward from zero. |
| `max` | `number` | `100` | Highest value. |
| `step` | `number` | `1` | Values snap to multiples of step from min. |
| `detents` | `number[]` | — | Values the cap clicks into while dragging or scrolling, within 3% of the range. |
| `arc` | `number` | `270` | Degrees of rotation from min to max, between 30 and 340. |
| `label` | `ReactNode` | — | Engraved legend under the dial. Names the slider unless aria-label is set. |
| `showValue` | `boolean` | `false` | Prints the formatted value under the label. |
| `formatValue` | `(value: number) => string` | — | Formats the printed value and aria-valuetext. |
| `name` | `string` | — | Submits the value with a form through a hidden input. |
| `color` | `NeonColor` | `inherited` | Palette name or hex. Falls back to --neon-accent, then cyan. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Dial of 56, 80 or 112px. |
| `disabled` | `boolean` | `false` | Darkens the ring, blocks input and removes the dial from the tab order. |
## Accessibility
- The dial has role="slider" with aria-valuemin, aria-valuemax, aria-valuenow, and aria-valuetext when formatValue is set.
- Arrow keys move by one step, Shift+Arrow and Page Up/Down by a tenth of the range, Home and End jump to the ends.
- Drag vertically to turn it; hold Shift for fine control or Alt for coarse.
- The wheel turns a knob once it has focus (click, drag or Tab to it) and the scroll starts over it, so a page scroll never gets caught on a knob. At either end of its travel the knob lets go and the page scrolls on.
- A visible label names the slider through aria-labelledby; pass aria-label when the legend is an abbreviation, like A, D, S and R.
## Source
`components/ui/knob.tsx`
```tsx
"use client";
import * as React from "react";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
// The dial is drawn in a 100-unit box, so every size shares one geometry.
// `travel` is how many pixels of vertical drag sweep the whole range.
const sizes = {
sm: { dial: "size-14 text-[10px]", minors: false, tick: 2, travel: 160, label: "text-[12px]", value: "text-[11px]" },
md: { dial: "size-20 text-[14px]", minors: true, tick: 1.4, travel: 200, label: "text-[12px]", value: "text-xs" },
lg: { dial: "size-28 text-[19px]", minors: true, tick: 1.1, travel: 240, label: "text-[12px]", value: "text-[13px]" },
} as const;
const RING = 39;
const CORE = "color-mix(in srgb, rgb(var(--neon)) 30%, white)";
// A detent catches the cap, which rings past it for a moment like a spring ball
// dropping into its notch. The value itself lands exactly on the detent.
const settleClass = {
none: "",
ease: "transition-transform duration-150 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none",
snap: "transition-transform duration-300 ease-[cubic-bezier(0.34,2.4,0.64,1)] motion-reduce:transition-none",
} as const;
function clamp(value: number, lower: number, upper: number) {
return Math.min(upper, Math.max(lower, value));
}
function decimalsOf(value: number) {
return (String(value).split(".")[1] ?? "").length;
}
function polar(angle: number, radius: number) {
const rad = ((angle - 90) * Math.PI) / 180;
return [50 + radius * Math.cos(rad), 50 + radius * Math.sin(rad)] as const;
}
function arcPath(from: number, to: number, radius: number) {
const [x1, y1] = polar(from, radius);
const [x2, y2] = polar(to, radius);
const large = Math.abs(to - from) > 180 ? 1 : 0;
const sweep = to > from ? 1 : 0;
return `M${x1.toFixed(2)} ${y1.toFixed(2)}A${radius} ${radius} 0 ${large} ${sweep} ${x2.toFixed(2)} ${y2.toFixed(2)}`;
}
type Settle = keyof typeof settleClass;
export interface KnobProps
extends Omit, "color" | "defaultValue" | "onChange" | "children"> {
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
size?: keyof typeof sizes;
value?: number;
defaultValue?: number;
onValueChange?: (value: number) => void;
/** Fires once a drag, key press or wheel gesture ends. */
onValueCommit?: (value: number) => void;
min?: number;
max?: number;
step?: number;
/** Values the cap clicks into while dragging or scrolling, like a center detent on a pan pot. */
detents?: number[];
/** Degrees of rotation from min to max. */
arc?: number;
/** Engraved legend under the dial. Also names the control. */
label?: React.ReactNode;
/** Prints the value under the label. */
showValue?: boolean;
/** Formats the printed value and the value read to screen readers. */
formatValue?: (value: number) => string;
/** Submits the value under this name with a surrounding form. */
name?: string;
disabled?: boolean;
}
const Knob = React.forwardRef(
(
{
className,
style,
color,
size = "md",
value: valueProp,
defaultValue,
onValueChange,
onValueCommit,
min = 0,
max = 100,
step = 1,
detents,
arc: arcProp = 270,
label,
showValue = false,
formatValue,
name,
disabled = false,
id: idProp,
"aria-label": ariaLabel,
"aria-labelledby": ariaLabelledBy,
onPointerDown,
onPointerMove,
onPointerUp,
onPointerCancel,
onKeyDown,
onKeyUp,
onDoubleClick,
...props
},
ref,
) => {
const autoId = React.useId();
const labelId = `${idProp ?? autoId}-label`;
const dialRef = React.useRef(null);
React.useImperativeHandle(ref, () => dialRef.current as HTMLDivElement);
const [uncontrolled, setUncontrolled] = React.useState(() => clamp(defaultValue ?? min, min, max));
const isControlled = valueProp !== undefined;
const value = clamp(isControlled ? valueProp : uncontrolled, min, max);
const [dragging, setDragging] = React.useState(false);
const [settle, setSettle] = React.useState("none");
const drag = React.useRef<{ y: number; raw: number; start: number } | null>(null);
const keyChanged = React.useRef(false);
const wheel = React.useRef({ last: -Infinity, inside: false, raw: null as number | null, start: 0, latest: 0, timer: 0 });
const wheelHandler = React.useRef<(event: WheelEvent) => void>(() => {});
const s = sizes[size];
const arc = clamp(arcProp, 30, 340);
const range = max - min || 1;
const decimals = Math.max(decimalsOf(step), decimalsOf(min));
// Bipolar ranges (pan, detune) light from zero outwards.
const origin = min < 0 && max > 0 ? 0 : min;
const angleOf = (v: number) => -arc / 2 + ((clamp(v, min, max) - min) / range) * arc;
const angle = angleOf(value);
const originAngle = angleOf(origin);
const litFraction = Math.abs(angle - originAngle) / arc;
function snapToStep(raw: number) {
return clamp(Number((Math.round((raw - min) / step) * step + min).toFixed(decimals)), min, max);
}
/** Lands on a detent when the raw position is close enough, otherwise on a step. */
function resolve(raw: number) {
const zone = range * 0.03;
const detent = detents?.find((d) => Math.abs(raw - d) <= zone);
return detent !== undefined ? clamp(detent, min, max) : snapToStep(raw);
}
function setValue(next: number, mode: Settle) {
if (next === value) return false;
if (!isControlled) setUncontrolled(next);
setSettle(mode);
onValueChange?.(next);
return true;
}
/** Pointer and wheel moves: detents get the springy settle, everything else tracks 1:1. */
function moveTo(raw: number) {
const next = resolve(raw);
const crossesDetent = detents?.some((d) => d === next || d === value) ?? false;
setValue(next, crossesDetent ? "snap" : "none");
return next;
}
function handlePointerDown(event: React.PointerEvent) {
onPointerDown?.(event);
if (disabled || event.defaultPrevented || event.button !== 0) return;
// Keeps text from selecting while dragging; we focus the dial ourselves.
event.preventDefault();
event.currentTarget.focus({ preventScroll: true });
event.currentTarget.setPointerCapture(event.pointerId);
drag.current = { y: event.clientY, raw: value, start: value };
setDragging(true);
}
function handlePointerMove(event: React.PointerEvent) {
onPointerMove?.(event);
const d = drag.current;
if (!d) return;
const factor = event.shiftKey ? 0.1 : event.altKey ? 4 : 1;
d.raw = clamp(d.raw + ((d.y - event.clientY) * factor * range) / s.travel, min, max);
d.y = event.clientY;
moveTo(d.raw);
}
function endDrag() {
const d = drag.current;
if (!d) return;
drag.current = null;
setDragging(false);
if (value !== d.start) onValueCommit?.(value);
}
function handleKeyDown(event: React.KeyboardEvent) {
onKeyDown?.(event);
if (disabled || event.defaultPrevented) return;
const big = Math.max(step, Math.round(range / 10 / step) * step);
const arrow = event.shiftKey ? big : step;
const delta: Record = {
ArrowUp: arrow,
ArrowRight: arrow,
ArrowDown: -arrow,
ArrowLeft: -arrow,
PageUp: big,
PageDown: -big,
Home: -Infinity,
End: Infinity,
};
if (!(event.key in delta)) return;
event.preventDefault();
if (setValue(snapToStep(clamp(value + delta[event.key], min, max)), "ease")) keyChanged.current = true;
}
function handleKeyUp(event: React.KeyboardEvent) {
onKeyUp?.(event);
if (!keyChanged.current) return;
keyChanged.current = false;
onValueCommit?.(value);
}
function handleWheel(event: WheelEvent) {
const gesture = wheel.current;
if (disabled || !gesture.inside) return;
// Shift turns the wheel sideways on some systems, so take whichever axis moved.
const delta = Math.abs(event.deltaY) >= Math.abs(event.deltaX) ? event.deltaY : event.deltaX;
// At the end of its travel the knob lets go, and the rest of the gesture scrolls the page.
const current = gesture.raw ?? value;
if ((delta > 0 && current <= min) || (delta < 0 && current >= max)) {
gesture.inside = false;
return;
}
event.preventDefault();
const pixels = event.deltaMode === 1 ? delta * 16 : delta;
const factor = event.shiftKey ? 0.1 : event.altKey ? 4 : 1;
if (gesture.raw === null) gesture.start = value;
const raw = clamp((gesture.raw ?? value) - (pixels * factor * range) / 2000, min, max);
gesture.raw = raw;
gesture.latest = moveTo(raw);
window.clearTimeout(gesture.timer);
gesture.timer = window.setTimeout(() => {
if (gesture.latest !== gesture.start) onValueCommit?.(gesture.latest);
}, 300);
}
React.useEffect(() => {
wheelHandler.current = handleWheel;
});
React.useEffect(() => {
const node = dialRef.current;
if (!node) return;
const gesture = wheel.current;
// The wheel belongs to the page until the knob has been picked up: only a
// gesture that begins on a focused knob turns it, so resting the pointer on
// one while reading never hijacks the scroll.
const track = (event: WheelEvent) => {
if (event.timeStamp - gesture.last > 300) {
gesture.inside = node.contains(event.target as Node) && document.activeElement === node;
gesture.raw = null;
}
gesture.last = event.timeStamp;
};
const turn = (event: WheelEvent) => wheelHandler.current(event);
window.addEventListener("wheel", track, { capture: true, passive: true });
node.addEventListener("wheel", turn, { passive: false });
return () => {
window.removeEventListener("wheel", track, { capture: true });
node.removeEventListener("wheel", turn);
window.clearTimeout(gesture.timer);
};
}, []);
const text = formatValue ? formatValue(value) : String(value);
const lit = !disabled;
// A stepped knob with a handful of positions marks each one; otherwise a 0–10 scale.
const positions = Math.round(range / step);
const stepped = positions <= 12 && Math.abs(positions * step - range) < 1e-9;
const divisions = stepped ? positions : s.minors ? 20 : 10;
const ticks: { angle: number; major: boolean }[] = [];
for (let i = 0; i <= divisions; i++) {
ticks.push({ angle: -arc / 2 + (i / divisions) * arc, major: stepped || !s.minors || i % 2 === 0 });
}
const litFrom = Math.min(angle, originAngle);
const litTo = Math.max(angle, originAngle);
return (
{
onPointerUp?.(event);
endDrag();
}}
onPointerCancel={(event) => {
onPointerCancel?.(event);
endDrag();
}}
onKeyDown={handleKeyDown}
onKeyUp={handleKeyUp}
onDoubleClick={(event) => {
onDoubleClick?.(event);
if (disabled || event.defaultPrevented || defaultValue === undefined) return;
const next = snapToStep(clamp(defaultValue, min, max));
if (setValue(next, "snap")) onValueCommit?.(next);
}}
className={cn(
"group/knob relative shrink-0 touch-none rounded-full outline-none",
"focus-visible:ring-2 focus-visible:ring-[rgb(var(--neon)/0.6)] focus-visible:ring-offset-2 focus-visible:ring-offset-[#05060a]",
disabled ? "cursor-not-allowed" : "cursor-ns-resize",
s.dial,
)}
>
{/* Light from the ring falling on the panel around the knob */}
{/* Printed scale and the unlit LED ring */}
{/* The lit part of the ring: a colored body with a near-white core */}
{lit && litTo - litFrom > 0.01 && (
)}
{/* The cap. Lighting stays put while the knurl and pointer turn. */}