detent dial.md

Detent Dial

Rotary knob that clicks from notch to notch and coasts when flicked, built with React and Motion.

Source: https://kokonutui.com/docs/inputs/detent-dial

Installation

npx shadcn@latest add @kokonutui/detent-dial

Props

Prop Type Default Description
label? string "Temperature" Accessible name, also shown inside the knob.
min? number 16
max? number 30
step? number 0.5
defaultValue? number 21 Initial value when uncontrolled. Double-clicking the knob returns here.
value? number Controlled value.
onValueChange? (value: number) => void
formatValue? (value: number) => string `(v) => \
${v.toFixed(1)}° Formats the readout, the end labels and aria-valuetext.
size? number 240 Diameter in px.
disabled? boolean false
className? string Extra classes for the root element.

Source

"use client";

/**
 * @author: @dorianbaffier
 * @description: Detent Dial
 * @version: 1.0.0
 * @date: 2026-10-13
 * @license: MIT
 * @website: https://kokonutui.com
 * @github: https://github.com/kokonut-labs/kokonutui
 */

import {
  AnimatePresence,
  type AnimationPlaybackControls,
  animate,
  motion,
  useMotionValue,
  useMotionValueEvent,
  useReducedMotion,
  useTransform,
  type Variants,
} from "motion/react";
import {
  type KeyboardEvent,
  type PointerEvent,
  useEffect,
  useId,
  useRef,
  useState,
} from "react";
import { cn } from "@/lib/utils";

// The dial sweeps 270°, from 7:30 to 4:30 on a clock face.
const SWEEP = 270;
const START_ANGLE = -135;
// How far (deg) the knob can be wound past either end. The pull flattens
// out as it approaches this, so it slows down instead of hitting a wall.
const MAX_OVERSHOOT = 16;
// While dragging, the knob is pulled this much toward the nearest notch,
// which is what makes it feel like it clicks from one step to the next.
const DETENT_PULL = 0.65;
const MAX_TICKS = 56;
// The swell that follows the indicator round the ring: extra length (px)
// at its peak, and how many degrees it spreads either side.
const WAVE_HEIGHT = 9;
const WAVE_WIDTH = 12;
// Pointer movement this close to the centre gives wild angle jumps.
const DEAD_ZONE = 14;
// Below this speed (fraction of the range per second) a release just
// settles into the nearest notch instead of coasting.
const FLICK_THRESHOLD = 0.4;
const VELOCITY_WINDOW_MS = 80;
// Seconds of travel a flick is worth: release speed × COAST = distance coasted.
const COAST = 0.3;
const SETTLE_SPRING = { type: "spring", duration: 0.35, bounce: 0.2 } as const;
const EASE_OUT = [0.23, 1, 0.32, 1] as const;

function damp(distance: number, max: number) {
  return max * (1 - Math.exp(-distance / max));
}

function clamp(value: number, min: number, max: number) {
  return Math.min(Math.max(value, min), max);
}

function snap(value: number, min: number, step: number) {
  return Number((Math.round((value - min) / step) * step + min).toFixed(10));
}

function polar(cx: number, cy: number, radius: number, angle: number) {
  const rad = (angle * Math.PI) / 180;
  // Rounded so the server and the browser, whose trig can differ in the
  // last digits, render identical markup.
  return {
    x: Math.round((cx + radius * Math.sin(rad)) * 100) / 100,
    y: Math.round((cy - radius * Math.cos(rad)) * 100) / 100,
  };
}

function pointerAngle(event: PointerEvent, rect: DOMRect) {
  const dx = event.clientX - (rect.left + rect.width / 2);
  const dy = event.clientY - (rect.top + rect.height / 2);
  return {
    angle: (Math.atan2(dx, -dy) * 180) / Math.PI,
    distance: Math.hypot(dx, dy),
  };
}

// navigator.vibrate is a no-op where unsupported (iOS, desktop). On
// Android it gives each notch a faint tick under the finger.
function hapticTick() {
  if (typeof navigator !== "undefined" && "vibrate" in navigator) {
    navigator.vibrate(1);
  }
}

export interface DetentDialProps {
  /** Accessible name, also shown inside the knob. */
  label?: string;
  min?: number;
  max?: number;
  step?: number;
  /** Initial value when uncontrolled. Double-clicking the knob returns here. */
  defaultValue?: number;
  /** Controlled value. */
  value?: number;
  onValueChange?: (value: number) => void;
  /** Formats the readout, the end labels and `aria-valuetext`. */
  formatValue?: (value: number) => string;
  /** Diameter in px. */
  size?: number;
  disabled?: boolean;
  className?: string;
}

export default function DetentDial({
  label = "Temperature",
  min = 16,
  max = 30,
  step = 0.5,
  defaultValue = 21,
  value: valueProp,
  onValueChange,
  formatValue = (v) => `${v.toFixed(1)}°`,
  size = 240,
  disabled = false,
  className,
}: DetentDialProps) {
  const labelId = useId();
  const knobRef = useRef<HTMLDivElement>(null);
  const tickRefs = useRef<(SVGLineElement | null)[]>([]);
  const tickLengths = useRef<number[]>([]);
  const reduceMotion = useReducedMotion();
  const range = max - min;

const initial = clamp(valueProp ?? defaultValue, min, max);
  const [value, setValue] = useState(initial);
  const [direction, setDirection] = useState<1 | -1>(1);
  const [grabbing, setGrabbing] = useState(false);
  const committed = useRef(initial);
  const pointerType = useRef("mouse");

const raw = useMotionValue(initial);
  const animation = useRef<AnimationPlaybackControls | null>(null);
  const drag = useRef<{
    id: number;
    rect: DOMRect;
    lastAngle: number;
    samples: { t: number; v: number }[];
  } | null>(null);

const rotation = useTransform(raw, (r) => {
    const degPerUnit = range === 0 ? 0 : SWEEP / range;
    if (r < min) {
      return START_ANGLE - damp((min - r) * degPerUnit, MAX_OVERSHOOT);
    }
    if (r > max) {
      return START_ANGLE + SWEEP + damp((r - max) * degPerUnit, MAX_OVERSHOOT);
    }
    const notch = snap(r, min, step);
    const pulled = notch + (r - notch) * (1 - DETENT_PULL);
    return START_ANGLE + (pulled - min) * degPerUnit;
  });

useMotionValueEvent(raw, "change", (r) => {
    const next = clamp(snap(r, min, step), min, max);
    if (next === committed.current) {
      return;
    }
    setDirection(next > committed.current ? 1 : -1);
    committed.current = next;
    setValue(next);
    onValueChange?.(next);
    if (pointerType.current === "touch") {
      hapticTick();
    }
  });

useEffect(() => {
    if (valueProp === undefined || drag.current) {
      return;
    }
    const next = clamp(valueProp, min, max);
    if (next !== committed.current) {
      animation.current?.stop();
      committed.current = next;
      setValue(next);
      raw.jump(next);
    }
  }, [valueProp, min, max, raw]);

useEffect(() => () => animation.current?.stop(), []);
  const settleTo = (target: number) => {
    animation.current?.stop();
    animation.current = animate(
      raw,
      target,
      reduceMotion ? { duration: 0 } : SETTLE_SPRING
    );
  };

const stepBy = (delta: number) => {
    animation.current?.stop();
    const target = clamp(snap(committed.current + delta, min, step), min, max);
    pointerType.current = "keyboard";
    raw.jump(target);
  };

const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {
    if (disabled || drag.current) {
      return;
    }
    if (event.pointerType === "mouse" && event.button !== 0) {
      return;
    }
    const rect = event.currentTarget.getBoundingClientRect();
    const { angle } = pointerAngle(event, rect);
    animation.current?.stop();
    pointerType.current = event.pointerType;
    event.currentTarget.setPointerCapture(event.pointerId);
    drag.current = {
      id: event.pointerId,
      rect,
      lastAngle: angle,
      samples: [{ t: event.timeStamp, v: raw.get() }],
    };
    setGrabbing(true);
  };

const handlePointerMove = (event: PointerEvent<HTMLDivElement>) => {
    const current = drag.current;
    if (!current || current.id !== event.pointerId) {
      return;
    }
    const { angle, distance } = pointerAngle(event, current.rect);
    if (distance < DEAD_ZONE) {
      current.lastAngle = angle;
      return;
    }
    let delta = angle - current.lastAngle;
    if (delta > 180) {
      delta -= 360;
    } else if (delta < -180) {
      delta += 360;
    }
    current.lastAngle = angle;
    const next = raw.get() + (delta / SWEEP) * range;
    raw.set(next);
    current.samples.push({ t: event.timeStamp, v: next });
    while (
      current.samples.length > 2 &&
      event.timeStamp - current.samples[0].t > VELOCITY_WINDOW_MS
    ) {
      current.samples.shift();
    }
  };

const handlePointerUp = (event: PointerEvent<HTMLDivElement>) => {
    const current = drag.current;
    if (!current || current.id !== event.pointerId) {
      return;
    }
    drag.current = null;
    setGrabbing(false);

const first = current.samples[0];
    const last = current.samples.at(-1) ?? first;
    const elapsed = (last.t - first.t) / 1000;
    const paused = event.timeStamp - last.t > VELOCITY_WINDOW_MS;
    const velocity = elapsed > 0 && !paused ? (last.v - first.v) / elapsed : 0;
    const position = raw.get();
    const inBounds = position >= min && position <= max;

if (
      reduceMotion ||
      !inBounds ||
      Math.abs(velocity) < range * FLICK_THRESHOLD
    ) {
      settleTo(clamp(snap(position, min, step), min, max));
      return;
    }
    animation.current?.stop();
    const target = clamp(
      snap(position + velocity * COAST, min, step),
      min,
      max
    );
    animation.current = animate(raw, target, {
      type: "spring",
      velocity,
      stiffness: 140,
      damping: 24,
      restDelta: 0.005,
    });
  };

const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    if (disabled) {
      return;
    }
    const big = Math.max(step, snap(range / 10, 0, step));
    const keySteps: Record<string, number> = {
      ArrowUp: step,
      ArrowRight: step,
      ArrowDown: -step,
      ArrowLeft: -step,
      PageUp: big,
      PageDown: -big,
      Home: min - committed.current,
      End: max - committed.current,
    };
    if (!(event.key in keySteps)) {
      return;
    }
    event.preventDefault();
    stepBy(keySteps[event.key]);
  };

const wheelStep = useRef({ disabled, step, stepBy });
  wheelStep.current = { disabled, step, stepBy };
  useEffect(() => {
    const knob = knobRef.current;
    if (!knob) {
      return;
    }
    let accumulated = 0;
    const onWheel = (event: WheelEvent) => {
      const latest = wheelStep.current;
      if (latest.disabled || document.activeElement !== knob) {
        return;
      }
      event.preventDefault();
      accumulated += event.deltaY;
      while (Math.abs(accumulated) >= 40) {
        const sign = Math.sign(accumulated);
        accumulated -= sign * 40;
        latest.stepBy(-sign * latest.step);
      }
    };
    knob.addEventListener("wheel", onWheel, { passive: false });
    return () => knob.removeEventListener("wheel", onWheel);
  }, []);

const center = size / 2;
  const tickCount = Math.max(1, Math.min(Math.round(range / step), MAX_TICKS));
  const valueFraction = range === 0 ? 0 : (value - min) / range;
  const activeTick = Math.round(valueFraction * tickCount);
  const knobSize = size * 0.64;
  const outer = size / 2 - 6;

function tickLength(i: number, indicatorAngle: number) {
    const angle = START_ANGLE + (i / tickCount) * SWEEP;
    const anchor = i === 0 || i === tickCount || i * 2 === tickCount;
    const major = i % 5 === 0;
    let base = 6;
    if (anchor) {
      base = 14;
    } else if (major) {
      base = 10;
    }
    const distance = (angle - indicatorAngle) / WAVE_WIDTH;
    return (
      Math.round((base + WAVE_HEIGHT * Math.exp(-distance * distance)) * 10) /
      10
    );
  }

function tickGeometry(i: number, length: number) {
    const angle = START_ANGLE + (i / tickCount) * SWEEP;
    return {
      a: polar(center, center, outer - length, angle),
      b: polar(center, center, outer, angle),
    };
  }

useMotionValueEvent(rotation, "change", (indicatorAngle) => {
    for (let i = 0; i <= tickCount; i++) {
      const line = tickRefs.current[i];
      const length = tickLength(i, indicatorAngle);
      if (!line || tickLengths.current[i] === length) {
        continue;
      }
      tickLengths.current[i] = length;
      const { a } = tickGeometry(i, length);
      line.setAttribute("x1", String(a.x));
      line.setAttribute("y1", String(a.y));
    }
  });
  const minLabel = polar(center, center, outer + 2, START_ANGLE - 12);
  const maxLabel = polar(center, center, outer + 2, START_ANGLE + SWEEP + 12);

return (
    <div
      className={cn(
        "relative select-none",
        disabled && "opacity-50",
        className
      )}
      style={{ width: size, height: size }}
    >
      <svg
        aria-hidden="true"
        className="absolute inset-0"
        height={size}
        viewBox={`0 0 ${size} ${size}`}
        width={size}
      >
        {Array.from({ length: tickCount + 1 }, (_, i) => {
          const lit = i <= activeTick;
          const current = i === activeTick;
          const length = tickLength(i, rotation.get());
          tickLengths.current[i] = length;
          const { a, b } = tickGeometry(i, length);
          return (
            <line
              className={cn(
                "transition-[stroke] duration-150",
                current && "stroke-orange-600 dark:stroke-orange-400",
                !current &&
                  (lit
                    ? "stroke-zinc-900 dark:stroke-zinc-100"
                    : "stroke-zinc-300 dark:stroke-zinc-700")
              )}
              key={i}
              ref={(node) => {
                tickRefs.current[i] = node;
              }}
              strokeLinecap="round"
              strokeWidth={current ? 2 : 1.5}
              x1={a.x}
              x2={b.x}
              y1={a.y}
              y2={b.y}
            />
          );
        })}
      </svg>

<span
        aria-hidden="true"
        className="absolute -translate-x-1/2 text-[11px] text-zinc-400 tabular-nums"
        style={{ left: minLabel.x, top: minLabel.y }}
      >
        {formatValue(min)}
      </span>
      <span
        aria-hidden="true"
        className="absolute -translate-x-1/2 text-[11px] text-zinc-400 tabular-nums"
        style={{ left: maxLabel.x, top: maxLabel.y }}
      >
        {formatValue(max)}
      </span>

<div
        aria-disabled={disabled || undefined}
        aria-labelledby={labelId}
        aria-valuemax={max}
        aria-valuemin={min}
        aria-valuenow={value}
        aria-valuetext={formatValue(value)}
        className={cn(
          "absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 touch-none rounded-full outline-none",
          "border border-zinc-200 bg-white shadow-[0_1px_2px_rgb(0_0_0/0.06),0_12px_32px_-12px_rgb(0_0_0/0.25)] dark:border-zinc-800 dark:bg-zinc-900 dark:shadow-[0_1px_2px_rgb(0_0_0/0.4),0_12px_32px_-12px_rgb(0_0_0/0.8)]",
          "transition-[border-color] duration-150 focus-visible:ring-2 focus-visible:ring-zinc-400 focus-visible:ring-offset-4 focus-visible:ring-offset-white dark:focus-visible:ring-offset-zinc-950",
          grabbing
            ? "cursor-grabbing border-zinc-300 dark:border-zinc-700"
            : "cursor-grab",
          disabled && "cursor-not-allowed"
        )}
        onDoubleClick={() => {
          if (!disabled) {
            pointerType.current = "mouse";
            settleTo(clamp(defaultValue, min, max));
          }
        }}
        onKeyDown={handleKeyDown}
        onLostPointerCapture={handlePointerUp}
        onPointerCancel={handlePointerUp}
        onPointerDown={handlePointerDown}
        onPointerMove={handlePointerMove}
        onPointerUp={handlePointerUp}
        ref={knobRef}
        role="slider"
        style={{ width: knobSize, height: knobSize }}
        tabIndex={disabled ? -1 : 0}
      >
        <motion.div
          aria-hidden="true"
          className="absolute inset-0"
          style={{ rotate: rotation }}
        >
          <span className="absolute top-2.5 left-1/2 h-3 w-[3px] -translate-x-1/2 rounded-full bg-zinc-900 dark:bg-zinc-100" />
        </motion.div>

<div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center">
          <span
            className="text-xs text-zinc-500 dark:text-zinc-400"
            id={labelId}
          >
            {label}
          </span>
          <RollingValue
            direction={direction}
            reduceMotion={Boolean(reduceMotion)}
            text={formatValue(value)}
          />
        </div>
      </div>
    </div>
  );
}

/**
 * Each character rolls on its own, so going from 21.5 to 22.0 only moves
 * the digits that changed. A touch of blur hides the overlap between the
 * outgoing and incoming glyph.
 */
const rollVariants: Variants = {
  enter: (offset: number) => ({
    opacity: 0,
    transform: `translateY(${offset}px)`,
    filter: offset === 0 ? "blur(0px)" : "blur(2px)",
  }),
  center: { opacity: 1, transform: "translateY(0px)", filter: "blur(0px)" },
  exit: (offset: number) => ({
    opacity: 0,
    transform: `translateY(${-offset}px)`,
    filter: offset === 0 ? "blur(0px)" : "blur(2px)",
  }),
};

function RollingValue({
  text,
  direction,
  reduceMotion,
}: {
  text: string;
  direction: 1 | -1;
  reduceMotion: boolean;
}) {
  const offset = reduceMotion ? 0 : direction * 10;
  return (
    <span
      aria-hidden="true"
      className="relative flex font-medium text-3xl text-zinc-900 tabular-nums tracking-tight dark:text-zinc-100"
    >
      {text.split("").map((char, index) => (
        <span
          className="relative inline-flex overflow-hidden"
          key={index}
        >
          <AnimatePresence custom={offset} initial={false} mode="popLayout">
            <motion.span
              animate="center"
              custom={offset}
              exit="exit"
              initial="enter"
              key={char}
              transition={{ duration: 0.16, ease: EASE_OUT }}
              variants={rollVariants}
            >
              {char}
            </motion.span>
          </AnimatePresence>
        </span>
      ))}
    </span>
  );
}