# Level dial

> 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.

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.

## Install

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

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

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/level-dial
- Registry item (source): https://hairlineui.com/r/level-dial.json

## 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.

```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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | – | The level. |
| `onValueChange` | `(value: number) => void` | – | Called as it’s dragged or stepped. |
| `min` | `number` | `0` | The low end. |
| `max` | `number` | `100` | The high end. |
| `step` | `number` | `1` | 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. |

## 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.

## What it handles

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.

- **Drag and keys**: Follows the pointer along the arc; arrows, Page keys, Home and End.
- **Jumps you can see**: Changes from outside arrive with light and a sweep of the arc.
- **Zones**: Named ranges that colour the arc and light the rim.
- **A whole card**: Title, badge, caption and your actions around the dial.
- **Past the ends**: Pointing past the arc’s ends snaps to the nearer one.
- **Screen readers**: A real slider, reading the value, unit and zone.

## Replaces

thermostat dial, circular slider, knob component, volume dial, radial slider

## Where it fits

- **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.

## Notes

- 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.

License: MIT (https://hairlineui.com/license#components)
