Skip to content
Browse documentation

A 270° dial for one level in a card: drag it and it follows, and when a preset sets it a crest of light spreads from its centre as the arc sweeps there.

Used forThermostatsAudioLightingLimits

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/level-dial.json

Registered the namespace? Then it’s shadcn add @hairline/level-dial. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • Thermostats

    A room’s temperature, with Boost and night eco as zones.

  • Audio

    Monitor or speaker level, from late night to reference.

  • Lighting

    Brightness or colour temperature for a room or a fixture.

  • Limits

    A spending cap or a threshold set by hand or by a plan.

What it handles for you

A dial that jumps when a preset changes it gives no sign anything happened, and a plain slider loses the feel of a real control.

Instead of wiring upthermostat dialcircular sliderknob componentvolume dialradial slider
  1. Drag and keys

    Follows the pointer along the arc; arrows, Page keys, Home and End.

  2. Jumps you can see

    Changes from outside arrive with light and a sweep of the arc.

  3. Zones

    Named ranges that colour the arc and light the rim.

  4. A whole card

    Title, badge, caption and your actions around the dial.

  5. Past the ends

    Pointing past the arc’s ends snaps to the nearer one.

  6. Screen readers

    A real slider, reading the value, unit and zone.

Overview

Thermostats, volume, brightness: a dial is the natural shape for one level, but when a preset or a schedule changes it, most dials just jump and nobody notices. Level dial follows your hand exactly when you drag along the arc or use the arrow keys. When the value changes from outside (a Boost button, a night schedule, another device), a crest of light spreads from the dial’s centre across the card, and under it the arc sweeps to the new value while the figure counts there. Name ranges of the dial as zones (Night eco, Holding, Boosting); a zone with a palette colours the arc and keeps the card’s rim lit while the value is in it, so the card says at a glance that it’s in a special mode.

States

drag
The arc, thumb and figure follow the pointer each move; the thumb grows from 5.5 to 7.5px while held.
jump
A value from outside plays a crest from the dial’s centre over 1.4s; at 36% the arc sweeps to the new value over 720ms (ease-out) and the figure counts with it.
zone
A zone with a palette gives the arc a gradient in its colour and lights the rim; its label sits under the figure.
reduced motion
Jumps land in place, with no light or sweep.

Usage

usage.tsx
import { LevelDial } from "@/components/level-dial";<LevelDial value={temp} onValueChange={setTemp} min={60} max={80} unit="°" label="Hallway temperature" title="Hallway" />

A thermostat with Boost

Drags update your state directly; the Boost button sets it from outside, so it arrives with the light.

example.tsx
"use client";import { useState } from "react";import { LevelDial } from "@/components/level-dial";export function Hallway() {  const [temp, setTemp] = useState(68);  async function boost() {    const res = await fetch("/api/thermostat/hallway/boost", { method: "POST" });    const { target } = await res.json();    setTemp(target);  }  return (    <LevelDial      value={temp}      onValueChange={(t) => {        setTemp(t);        fetch("/api/thermostat/hallway", { method: "PUT", body: JSON.stringify({ target: t }) });      }}      min={60}      max={80}      unit="°"      label="Hallway temperature"      title="Hallway"      zones={[{ to: 64, label: "Night eco", palette: "azure" }, { to: 71, label: "Holding" }, { to: 80, label: "Boosting", palette: "solar" }]}    >      <button onClick={boost}>Boost for 30 min</button>    </LevelDial>  );}

Props

value
number
The level.
onValueChange
(value: number) => void
Called as it’s dragged or stepped.
min= 0
number
The low end.
max= 100
number
The high end.
step= 1
number
The smallest change.
unit
string
Set after the figure: "°", "dB", "%".
label
string
Names the dial for screen readers.
title
ReactNode
The card’s heading.
badge
ReactNode
Top right of the card.
caption
ReactNode
A line under the dial.
zones
{ to: number; label: string; palette?: … }[]
Named ranges, lowest first; a palette colours the arc and lights the rim.
children
ReactNode
Your actions, at the foot of the card.

Accessibility and motion

  • A change the dial sent itself (drag or keys) shows at once; any other value is treated as a jump and gets the light.
  • The light is a 2D canvas over the card, drawn only while a crest crosses; the dial underneath is plain SVG.
  • The slider role sits on the dial with the value, unit and zone in its text; the figure in the middle is hidden from screen readers to avoid reading it twice.
  • Reduced motion drops the crest and the sweep.

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

Source

"use client";import * as React from "react";import {  LightSurface,  clamp,  easeOutCubic,  resolvePalette,  useLightHeld,  useLightReducedMotion,  type LightPalette,  type LightPaletteName,  type LightSurfaceHandle,} from "./light-surface";/* ───────────────────────────────────────────────────────── * LEVEL DIAL: a 270° dial for one level, in a card * *   turn     drag along the arc, or use the arrow keys; the *            arc and the figure follow at once *   jump     when the value changes from outside (a preset, a *            schedule, another device), a crest of light spreads from *            the dial's centre; under it the arc sweeps to the *            new value and the figure counts there *   zones    name ranges of the dial (Late night, Reference); *            a zone with a palette colours the arc and keeps *            the card's rim lit while the value is in it * * Reduced motion: jumps land in place, with no light. * ───────────────────────────────────────────────────────── */export interface LevelZone {  /** The zone covers values up to and including this one. */  to: number;  label: string;  /** Colours the arc and lights the rim while the value is in this zone. */  palette?: LightPaletteName | LightPalette;}export interface LevelDialProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title" | "onChange"> {  value: number;  onValueChange?: (value: number) => void;  min?: number;  max?: number;  step?: number;  /** Set after the figure: "°", "dB", "%". */  unit?: string;  /** Names the dial for screen readers. */  label: string;  /** The card's heading. */  title?: React.ReactNode;  /** Top right of the card: a mode, a badge. */  badge?: React.ReactNode;  /** A line under the dial. */  caption?: React.ReactNode;  /** Named ranges, lowest first. */  zones?: LevelZone[];  /** Your actions, at the foot of the card. */  children?: React.ReactNode;}const START = 135;const SWEEP = 270;const CX = 120;const CY = 120;const R = 84;const polar = (deg: number, r = R) => ({ x: CX + r * Math.cos((deg * Math.PI) / 180), y: CY + r * Math.sin((deg * Math.PI) / 180) });function arc(from: number, to: number) {  const a = polar(from);  const b = polar(to);  return `M ${a.x.toFixed(2)} ${a.y.toFixed(2)} A ${R} ${R} 0 ${to - from > 180 ? 1 : 0} 1 ${b.x.toFixed(2)} ${b.y.toFixed(2)}`;}/** Glides to a new target when asked to, otherwise follows it exactly. */function useGlide(target: number, glide: boolean, reduced: boolean) {  const [anim, setAnim] = React.useState<number | null>(null);  const current = React.useRef(target);  const raf = React.useRef(0);  React.useEffect(() => {    cancelAnimationFrame(raf.current);    if (!glide || reduced) {      current.current = target;      raf.current = requestAnimationFrame(() => setAnim(null));      return () => cancelAnimationFrame(raf.current);    }    const from = current.current;    if (from === target) return;    const start = performance.now();    const step = (now: number) => {      const k = Math.min(1, (now - start) / 720);      current.current = from + (target - from) * easeOutCubic(k);      setAnim(k < 1 ? current.current : null);      if (k < 1) raf.current = requestAnimationFrame(step);    };    raf.current = requestAnimationFrame(step);    return () => cancelAnimationFrame(raf.current);  }, [target, glide, reduced]);  return anim ?? target;}export function LevelDial({  value,  onValueChange,  min = 0,  max = 100,  step = 1,  unit = "",  label,  title,  badge,  caption,  zones,  children,  className = "",  ...props}: LevelDialProps) {  const surface = React.useRef<LightSurfaceHandle>(null);  const svg = React.useRef<SVGSVGElement>(null);  const reduced = useLightReducedMotion();  const [dragging, setDragging] = React.useState(false);  // The last value we sent: anything else that arrives was set from outside, and gets the light.  const [local, setLocal] = React.useState<number | null>(null);  const external = value !== local;  const zoneOf = (v: number) => zones?.find((z) => v <= z.to) ?? zones?.[zones.length - 1];  const landed = useLightHeld(value, external ? `x${value}` : "local", surface, () => {    if (!external) return null;    const card = surface.current?.element();    const dial = svg.current;    let origin = { x: 0.5, y: 0.44 };    if (card && dial) {      const c = card.getBoundingClientRect();      const d = dial.getBoundingClientRect();      origin = { x: (d.left + d.width / 2 - c.left) / c.width, y: (d.top + (d.height * CY) / 218 - c.top) / c.height };    }    return { direction: "radial", origin, palette: zoneOf(value)?.palette ?? "solar" };  });  const shown = clamp(useGlide(landed, external, reduced), min, max);  const zone = zoneOf(Math.round(shown));  const pal = zone?.palette ? resolvePalette(zone.palette) : null;  const angle = START + ((shown - min) / (max - min || 1)) * SWEEP;  const thumb = polar(angle);  const gradientId = React.useId();  const send = (v: number) => {    const next = clamp(Math.round(v / step) * step, min, max);    if (next === value) return;    setLocal(next);    onValueChange?.(next);  };  const fromPointer = (clientX: number, clientY: number) => {    const el = svg.current;    if (!el) return;    const r = el.getBoundingClientRect();    const deg = (Math.atan2(clientY - (r.top + (r.height * CY) / 218), clientX - (r.left + r.width / 2)) * 180) / Math.PI;    const around = ((((deg % 360) + 360) % 360) - START + 360) % 360;    // Past the ends of the arc, the nearer end wins.    const k = around <= SWEEP ? around / SWEEP : around - SWEEP < 360 - around ? 1 : 0;    send(min + k * (max - min));  };  const ink = pal ? pal.ink : "var(--foreground)";  const figure = Math.round(shown);  return (    <LightSurface      ref={surface}      palette={zone?.palette ?? "solar"}      direction="radial"      lit={!!pal}           className={`flex flex-col rounded-[30px] ${className}`}      {...props}    >      <div className="flex h-full flex-col px-6 pb-6 pt-6">        {(title || badge) && (          <div className="flex min-h-7 items-center justify-between gap-3">            <div className="text-[15px] font-medium tracking-[-0.01em] text-foreground">{title}</div>            {badge}          </div>        )}        <div className="my-1 flex flex-col items-center">          <div            role="slider"            tabIndex={0}            aria-label={label}            aria-valuemin={min}            aria-valuemax={max}            aria-valuenow={value}            aria-valuetext={`${value}${unit}${zoneOf(value)?.label ? `, ${zoneOf(value)?.label}` : ""}`}            onKeyDown={(e) => {              const big = Math.max(step, (max - min) / 10);              const by: Record<string, number> = { ArrowRight: step, ArrowUp: step, ArrowLeft: -step, ArrowDown: -step, PageUp: big, PageDown: -big };              if (e.key in by) send(value + by[e.key]);              else if (e.key === "Home") send(min);              else if (e.key === "End") send(max);              else return;              e.preventDefault();            }}            className="relative flex w-full max-w-[236px] items-center justify-center rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring/50"          >            <svg              ref={svg}              viewBox="0 0 240 218"              className={`aspect-[240/218] w-full max-w-[236px] touch-none select-none ${dragging ? "cursor-grabbing" : "cursor-grab"}`}              onPointerDown={(e) => {                e.currentTarget.setPointerCapture(e.pointerId);                setDragging(true);                fromPointer(e.clientX, e.clientY);              }}              onPointerMove={(e) => dragging && fromPointer(e.clientX, e.clientY)}              onPointerUp={() => setDragging(false)}              onPointerCancel={() => setDragging(false)}            >              {pal && (                <defs>                  <linearGradient id={gradientId} x1="0%" y1="100%" x2="100%" y2="0%">                    <stop offset="0%" stopColor={pal.ink} />                    <stop offset="100%" stopColor={`color-mix(in oklab, ${pal.ink} 45%, white)`} />                  </linearGradient>                </defs>              )}              <path d={arc(START, START + SWEEP)} fill="none" stroke="color-mix(in oklab, var(--foreground) 11%, transparent)" strokeWidth="7.5" strokeLinecap="round" />              {shown > min && (                <path d={arc(START, angle)} fill="none" stroke={pal ? `url(#${gradientId})` : "var(--foreground)"} strokeWidth="7.5" strokeLinecap="round" />              )}              <circle                cx={thumb.x}                cy={thumb.y}                r={dragging ? 7.5 : 5.5}                fill="var(--card)"                stroke={ink}                strokeWidth="2.5"                className="transition-[r] duration-150 motion-reduce:transition-none"              />              <text x="62" y="206" textAnchor="middle" className="fill-muted-foreground font-mono text-[12px] tabular-nums">                {min}              </text>              <text x="178" y="206" textAnchor="middle" className="fill-muted-foreground font-mono text-[12px] tabular-nums">                {max}              </text>            </svg>            <div aria-hidden className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center pt-1 [container-type:inline-size]">              <div className="flex items-baseline gap-0.5">                <span className="text-[clamp(34px,15cqi,46px)] font-medium leading-none tracking-[-0.04em] tabular-nums text-foreground">{figure}</span>                {unit && <span className="text-[16px] font-medium text-muted-foreground">{unit}</span>}              </div>              {zone?.label && (                <div                  className="mt-1.5 text-[13px] font-medium transition-colors duration-300"                  style={{ color: pal ? `color-mix(in oklab, ${pal.ink} 70%, var(--foreground))` : "var(--muted-foreground)" }}                >                  {zone.label}                </div>              )}            </div>          </div>          {caption && <p className="mt-1 text-center text-[13px] tabular-nums text-muted-foreground">{caption}</p>}        </div>        {children && <div className="mt-auto pt-4">{children}</div>}      </div>    </LightSurface>  );}

Registry item: /r/level-dial.json