# Rotary knob

A matte charcoal plastic knob with a white indicator line over a scale printed on the faceplate, as a skirted knob or a pointer knob. Turn it by dragging, scrolling or with the arrow keys, and it clicks at each tick.

Source: https://www.ui95.dev/hardware/rotary-knob

## Examples

```tsx
"use client"

import * as React from "react"

import { Faceplate, Legend } from "@/components/hardware/faceplate"
import { Lamp } from "@/components/hardware/lamp"
import { RotaryKnob } from "@/components/hardware/rotary-knob"

import type { ShowcaseDemo } from "../types"

function AmpSection() {
  const [volume, setVolume] = React.useState(62)
  return (
    <Faceplate>
      <div className="flex flex-col gap-3">
        <Legend size="lg">Output</Legend>
        <div className="flex items-center gap-6">
          <RotaryKnob label="Volume" value={volume} onValueChange={setVolume} size="lg" />
          <RotaryKnob label="Bass" defaultValue={45} />
          <RotaryKnob label="Treble" defaultValue={70} />
          <Lamp on={volume >= 90} label="Clip" />
        </div>
      </div>
    </Faceplate>
  )
}

export const demo: ShowcaseDemo = {
  span: "full",
  variants: [
    { label: "skirted on putty", render: () => <AmpSection /> },
    {
      label: "pointer on khaki",
      render: () => (
        <Faceplate finish="khaki">
          <div className="flex items-center gap-6">
            <RotaryKnob label="Fine" variant="pointer" size="sm" defaultValue={30} />
            <RotaryKnob label="Gain" variant="pointer" defaultValue={50} />
            <RotaryKnob label="Master" variant="pointer" size="lg" defaultValue={80} />
          </div>
        </Faceplate>
      ),
    },
    {
      label: "coloured caps, stepped and disabled on cream",
      render: () => (
        <Faceplate finish="cream">
          <div className="flex items-center gap-6">
            <RotaryKnob label="Tone" min={0} max={10} step={1} defaultValue={4} cap="red" />
            <RotaryKnob label="Focus" defaultValue={55} cap="green" />
            <RotaryKnob label="Intensity" defaultValue={35} cap="amber" />
            <RotaryKnob label="Locked" defaultValue={20} disabled />
          </div>
        </Faceplate>
      ),
    },
  ],
}
```

## Installation

```bash
npx shadcn@latest add https://www.ui95.dev/r/rotary-knob.json
```

Run it in a Radix shadcn project that already has the UI95 theme.

Add these items first:

- [hardware](https://www.ui95.dev/hardware/hardware)

`components/hardware/rotary-knob.css`

```tsx
[data-part="knob"] {
  --hw-knob-size: 64px;
  display: inline-flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
}

[data-part="knob"][data-size="sm"] {
  --hw-knob-size: 40px;
}

[data-part="knob"][data-size="lg"] {
  --hw-knob-size: 96px;
}

[data-part="knob-mount"] {
  position: relative;
  display: grid;
  place-items: center;
  width: calc(var(--hw-knob-size) * 1.5);
  height: calc(var(--hw-knob-size) * 1.5);
}

[data-part="knob-scale"] {
  position: absolute;
  inset: 0;
  overflow: visible;
  color: var(--hw-legend);
}

[data-part="knob-scale"] line {
  stroke: currentColor;
  stroke-width: 0.9;
  stroke-linecap: butt;
  opacity: 0.6;
}

[data-part="knob-scale"] line[data-major] {
  stroke-width: 1.5;
  opacity: 0.92;
}

[data-part="knob-scale"] text {
  fill: currentColor;
  font-family: var(--hw-font);
  font-size: 7px;
  font-weight: 700;
  font-stretch: condensed;
  text-anchor: middle;
  dominant-baseline: central;
  opacity: 0.92;
}

[data-part="knob"][data-size="sm"] [data-part="knob-scale"] text {
  display: none;
}

[data-part="knob-body"] {
  position: relative;
  width: var(--hw-knob-size);
  height: var(--hw-knob-size);
  border-radius: 50%;
  cursor: grab;
  touch-action: none;
  outline: none;
}

[data-part="knob-face"] {
  display: block;
  width: 100%;
  height: 100%;
  overflow: visible;
  filter: drop-shadow(1px 2px 1.2px rgb(var(--hw-shadow-tint) / 0.5)) drop-shadow(3px 6px 5px rgb(var(--hw-shadow-tint) / 0.35));
  transition: filter 80ms ease-out, scale 80ms ease-out;
}

[data-part="knob-body"][data-dragging] {
  cursor: grabbing;
}

[data-part="knob-body"][data-dragging] [data-part="knob-face"] {
  scale: 0.985;
  filter: drop-shadow(1px 1px 1px rgb(var(--hw-shadow-tint) / 0.55)) drop-shadow(2px 4px 3px rgb(var(--hw-shadow-tint) / 0.3));
}

[data-part="knob-body"][aria-disabled] {
  cursor: not-allowed;
}

[data-part="knob-body"][aria-disabled] [data-part="knob-face"] {
  opacity: 0.72;
}

[data-part="knob-body"]:focus-visible {
  box-shadow: 0 0 0 3px color-mix(in oklab, var(--hw-amber-lit) 75%, transparent);
}

[data-part="knob-turn"] {
  rotate: var(--hw-turn);
}

[data-part="knob-skirt"],
[data-part="knob-cap"] {
  stroke-width: 1.4;
}

[data-part="knob-flute"] {
  stroke: rgb(0 0 0 / 0.45);
  stroke-width: 2;
}

[data-part="knob-dish"] {
  stroke: rgb(255 255 255 / 0.07);
  stroke-width: 0.8;
}

[data-part="knob-index"] {
  stroke: #ece5d3;
  stroke-width: 3;
  stroke-linecap: round;
}

@media (prefers-reduced-motion: reduce) {
  [data-part="knob-face"] {
    transition: none;
  }
}
```

`components/hardware/rotary-knob.tsx`

```tsx
"use client"

import "./hardware.css"
import "./rotary-knob.css"

import * as React from "react"

type RotaryKnobSize = "sm" | "md" | "lg"

type RotaryKnobVariant = "skirted" | "pointer"

type RotaryKnobCap = "red" | "amber" | "green" | "slate"

type RotaryRange = { min: number; max: number; step: number }

const SWEEP_DEGREES = 270

const DRAG_SPAN_PX = 220

const FINE_DRAG_FACTOR = 0.1

const PAGE_FRACTION = 0.1

const SCALE_MAJOR_TICKS = 11

const SCALE_MINOR_PER_MAJOR = 2

function snapToRange(value: number, { min, max, step }: RotaryRange): number {
  const stepped = Math.round((value - min) / step) * step + min
  const clamped = Math.min(max, Math.max(min, stepped))
  return Number(clamped.toFixed(10))
}

function toTurn(value: number, { min, max }: RotaryRange): number {
  const share = max > min ? (value - min) / (max - min) : 0
  return share * SWEEP_DEGREES - SWEEP_DEGREES / 2
}

function nextFromKey(key: string, value: number, range: RotaryRange): number | null {
  const page = Math.max(range.step, (range.max - range.min) * PAGE_FRACTION)
  switch (key) {
    case "ArrowUp":
    case "ArrowRight":
      return value + range.step
    case "ArrowDown":
    case "ArrowLeft":
      return value - range.step
    case "PageUp":
      return value + page
    case "PageDown":
      return value - page
    case "Home":
      return range.min
    case "End":
      return range.max
    default:
      return null
  }
}

function useRotaryInput(value: number, range: RotaryRange, setValue: (next: number) => void, disabled: boolean) {
  const ref = React.useRef<HTMLDivElement>(null)
  const drag = React.useRef<{ x: number; y: number; value: number } | null>(null)
  const [isDragging, setIsDragging] = React.useState(false)

  const onWheel = React.useEffectEvent((event: WheelEvent) => {
    if (disabled || event.deltaY === 0) {
      return
    }
    event.preventDefault()
    setValue(snapToRange(value - Math.sign(event.deltaY) * range.step, range))
  })

  React.useEffect(() => {
    const element = ref.current
    if (!element) {
      return
    }
    const listener = (event: WheelEvent) => onWheel(event)
    element.addEventListener("wheel", listener, { passive: false })
    return () => element.removeEventListener("wheel", listener)
  }, [])

  const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
    if (disabled || event.button !== 0) {
      return
    }
    event.currentTarget.setPointerCapture(event.pointerId)
    drag.current = { x: event.clientX, y: event.clientY, value }
    setIsDragging(true)
  }

  const onPointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
    const start = drag.current
    if (!start) {
      return
    }
    const travel = event.clientX - start.x - (event.clientY - start.y)
    const factor = event.shiftKey ? FINE_DRAG_FACTOR : 1
    setValue(snapToRange(start.value + (travel / DRAG_SPAN_PX) * (range.max - range.min) * factor, range))
  }

  const endDrag = () => {
    drag.current = null
    setIsDragging(false)
  }

  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
    const next = disabled ? null : nextFromKey(event.key, value, range)
    if (next === null) {
      return
    }
    event.preventDefault()
    setValue(snapToRange(next, range))
  }

  return {
    ref,
    isDragging,
    handlers: { onPointerDown, onPointerMove, onPointerUp: endDrag, onPointerCancel: endDrag, onLostPointerCapture: endDrag, onKeyDown },
  }
}

function polar(radius: number, radians: number) {
  return { x: Number((Math.cos(radians) * radius).toFixed(3)), y: Number((Math.sin(radians) * radius).toFixed(3)) }
}

const SCALE_TICK_COUNT = (SCALE_MAJOR_TICKS - 1) * SCALE_MINOR_PER_MAJOR + 1

const SCALE_TICKS = Array.from({ length: SCALE_TICK_COUNT }, (_, index) => {
  const isMajor = index % SCALE_MINOR_PER_MAJOR === 0
  const radians = ((index / (SCALE_TICK_COUNT - 1)) * SWEEP_DEGREES - SWEEP_DEGREES / 2 - 90) * (Math.PI / 180)
  return {
    index,
    isMajor,
    inner: polar(36.5, radians),
    outer: polar(isMajor ? 41 : 39.5, radians),
    numeral: isMajor ? { ...polar(46, radians), text: String(index / SCALE_MINOR_PER_MAJOR) } : null,
  }
})

function KnobScale() {
  return (
    <svg aria-hidden data-part="knob-scale" viewBox="-50 -50 100 100">
      {SCALE_TICKS.map(({ index, isMajor, inner, outer, numeral }) => (
        <g key={index}>
          <line x1={inner.x} y1={inner.y} x2={outer.x} y2={outer.y} data-major={isMajor ? "" : undefined} />
          {numeral && (
            <text x={numeral.x} y={numeral.y}>
              {numeral.text}
            </text>
          )}
        </g>
      ))}
    </svg>
  )
}

const FLUTE_COUNT = 36

const POINTER_ARM_CLEARANCE_DEGREES = 40

function flutes(inner: number, outer: number, skipArm: boolean) {
  return Array.from({ length: FLUTE_COUNT }, (_, index) => (index / FLUTE_COUNT) * 360)
    .filter((degrees) => !skipArm || Math.abs(((degrees + 180) % 360) - 180) > POINTER_ARM_CLEARANCE_DEGREES)
    .map((degrees) => {
      const radians = (degrees - 90) * (Math.PI / 180)
      return { degrees, from: polar(inner, radians), to: polar(outer, radians) }
    })
}

const SKIRTED_FLUTES = flutes(30.5, 34, false)

const POINTER_FLUTES = flutes(26.5, 30, true)

const POINTER_PATH = "M -14.08 -26.49 C -10 -36 -5 -46 0 -47 C 5 -46 10 -36 14.08 -26.49 A 30 30 0 1 1 -14.08 -26.49 Z"

const CAP_FILL: Record<RotaryKnobCap, string> = {
  red: "var(--hw-red)",
  amber: "var(--hw-amber)",
  green: "var(--hw-green)",
  slate: "var(--hw-slate)",
}

function KnobFace({ variant, cap, turn }: { variant: RotaryKnobVariant; cap?: RotaryKnobCap; turn: number }) {
  const id = React.useId().replace(/[^a-zA-Z0-9]/g, "")
  const light = `rotate(${-turn})`
  const isSkirted = variant === "skirted"
  return (
    <svg aria-hidden data-part="knob-face" viewBox="-50 -50 100 100">
      <defs>
        <radialGradient id={`${id}-body`} gradientUnits="userSpaceOnUse" cx="-20" cy="-24" r="82" gradientTransform={light}>
          <stop offset="0" stopColor="#4d4a46" />
          <stop offset="0.42" stopColor="#2c2a28" />
          <stop offset="1" stopColor="#141312" />
        </radialGradient>
        <radialGradient id={`${id}-dish`} gradientUnits="userSpaceOnUse" cx="10" cy="12" r="34" gradientTransform={light}>
          <stop offset="0" stopColor="#3a3734" />
          <stop offset="1" stopColor="#1c1b19" />
        </radialGradient>
        <linearGradient id={`${id}-rim`} gradientUnits="userSpaceOnUse" x1="-34" y1="-34" x2="34" y2="34" gradientTransform={light}>
          <stop offset="0" stopColor="#8f8a82" />
          <stop offset="0.5" stopColor="#2a2826" />
          <stop offset="1" stopColor="#050505" />
        </linearGradient>
        <radialGradient id={`${id}-insert`} gradientUnits="userSpaceOnUse" cx="6" cy="8" r="20" gradientTransform={light}>
          <stop offset="0" stopColor="#ffffff" stopOpacity="0.12" />
          <stop offset="1" stopColor="#000000" stopOpacity="0.35" />
        </radialGradient>
      </defs>
      <g data-part="knob-turn">
        {isSkirted ? (
          <>
            <circle r="48" fill={`url(#${id}-body)`} stroke={`url(#${id}-rim)`} data-part="knob-skirt" />
            <line x1="0" y1="-46.5" x2="0" y2="-38" data-part="knob-index" />
            <circle r="34" fill={`url(#${id}-body)`} stroke={`url(#${id}-rim)`} data-part="knob-cap" />
            {SKIRTED_FLUTES.map(({ degrees, from, to }) => (
              <line key={degrees} x1={from.x} y1={from.y} x2={to.x} y2={to.y} data-part="knob-flute" />
            ))}
            <circle r="27" fill={`url(#${id}-dish)`} data-part="knob-dish" />
          </>
        ) : (
          <>
            <path d={POINTER_PATH} fill={`url(#${id}-body)`} stroke={`url(#${id}-rim)`} data-part="knob-cap" />
            {POINTER_FLUTES.map(({ degrees, from, to }) => (
              <line key={degrees} x1={from.x} y1={from.y} x2={to.x} y2={to.y} data-part="knob-flute" />
            ))}
            <circle r="21" fill={`url(#${id}-dish)`} data-part="knob-dish" />
          </>
        )}
        {cap && (
          <>
            <circle r={isSkirted ? 17 : 13} style={{ fill: CAP_FILL[cap] }} />
            <circle r={isSkirted ? 17 : 13} fill={`url(#${id}-insert)`} />
          </>
        )}
        <line x1="0" y1={isSkirted ? -9 : -12} x2="0" y2={isSkirted ? -30 : -43} data-part="knob-index" />
      </g>
    </svg>
  )
}

type RotaryKnobProps = Omit<React.ComponentProps<"div">, "defaultValue" | "onChange"> & {
  label: string
  value?: number
  defaultValue?: number
  onValueChange?: (value: number) => void
  min?: number
  max?: number
  step?: number
  size?: RotaryKnobSize
  variant?: RotaryKnobVariant
  cap?: RotaryKnobCap
  disabled?: boolean
}

function RotaryKnob({
  label,
  value: controlled,
  defaultValue,
  onValueChange,
  min = 0,
  max = 100,
  step = 1,
  size = "md",
  variant = "skirted",
  cap,
  disabled = false,
  ...props
}: RotaryKnobProps) {
  const range = { min, max, step }
  const [stored, setStored] = React.useState(() => snapToRange(defaultValue ?? min, range))
  const value = controlled ?? stored
  const setValue = (next: number) => {
    if (next === value) {
      return
    }
    setStored(next)
    onValueChange?.(next)
  }
  const { ref, isDragging, handlers } = useRotaryInput(value, range, setValue, disabled)
  const turn = toTurn(value, range)

  return (
    <div data-hw="" data-part="knob" data-size={size} data-variant={variant} {...props}>
      <div data-part="knob-mount">
        <KnobScale />
        <div
          ref={ref}
          role="slider"
          tabIndex={disabled ? -1 : 0}
          aria-label={label}
          aria-valuemin={min}
          aria-valuemax={max}
          aria-valuenow={value}
          aria-disabled={disabled || undefined}
          data-slot="rotary-knob"
          data-part="knob-body"
          data-dragging={isDragging ? "" : undefined}
          style={{ "--hw-turn": `${turn}deg` } as React.CSSProperties}
          {...handlers}
        >
          <KnobFace variant={variant} cap={cap} turn={turn} />
        </div>
      </div>
      <span data-part="legend">{label}</span>
    </div>
  )
}

export { RotaryKnob, type RotaryKnobCap, type RotaryKnobSize, type RotaryKnobVariant }
```

## Notes

variant="skirted" | "pointer" picks the knob shape, and cap="red" | "amber" | "green" | "slate" adds a coloured cap insert. Drag up or right to turn it up, and hold Shift for fine control. The wheel and the arrow keys move one step, Page Up and Page Down a tenth of the range, Home and End to the stops. It is a role="slider", so screen readers announce its value. The light stays at the top-left while the knob turns. With the sound item installed, data-slot="rotary-knob" plays knob.tick at each printed tick.

## API reference

### RotaryKnob

| Prop | Type | Default |
| --- | --- | --- |
| `label` * | `string` | - |
| `value` | `number` | - |
| `defaultValue` | `number` | - |
| `onValueChange` | `((value: number) => void)` | - |
| `min` | `number` | `0` |
| `max` | `number` | `100` |
| `step` | `number` | `1` |
| `size` | `RotaryKnobSize` | `"md"` |
| `variant` | `RotaryKnobVariant` | `"skirted"` |
| `cap` | `RotaryKnobCap` | - |
| `disabled` | `boolean` | `false` |

## Sounds

- `knob.tick`
