);
}
```
### Zones
Printed bands for cold, normal and hot. The band holding the value lights up.
```tsx
"use client";
import * as React from "react";
import { Gauge } from "@/components/ui/gauge";
import { Slider } from "@/components/ui/slider";
const zones = [
{ from: 50, to: 70, color: "blue" },
{ from: 80, to: 105, color: "green" },
{ from: 115, to: 130, color: "red" },
];
export default function GaugeZones() {
const [temp, setTemp] = React.useState(92);
return (
);
}
```
### Live data
Feed it new values as often as you like; the needle springs to each one without re-rendering the dial.
```tsx
"use client";
import * as React from "react";
import { Gauge } from "@/components/ui/gauge";
const hosts = ["api-1", "api-2", "worker"];
export default function GaugeLive() {
const [load, setLoad] = React.useState([42, 67, 18]);
React.useEffect(() => {
// A random walk with a pull toward each host's usual load.
const usual = [45, 70, 25];
const id = window.setInterval(() => {
setLoad((current) =>
current.map((v, i) => {
const next = v + (usual[i] - v) * 0.15 + (Math.random() - 0.5) * 22;
return Math.round(Math.min(100, Math.max(0, next)));
}),
);
}, 1400);
return () => window.clearInterval(id);
}, []);
return (
{hosts.map((host, i) => (
`${v}%`}
/>
))}
);
}
```
### Sizes and colors
Small dials print their legends larger so they stay readable. className can set any other width.
```tsx
import { Gauge } from "@/components/ui/gauge";
export default function GaugeSizes() {
return (
);
}
```
## API reference
### Gauge
Accepts every div attribute; the ref points at the root, which has role="meter".
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | Current reading, clamped to min and max. |
| `min` | `number` | `0` | Start of the scale. |
| `max` | `number` | `100` | End of the scale. |
| `label` | `string` | — | Legend printed on the dial. Also the accessible name unless aria-label is set. |
| `unit` | `string` | — | Printed under the readout and read after the value. |
| `ticks` | `number` | `10` | Numbered intervals on the scale. Numerals shrink, then skip, to fit. |
| `redline` | `number` | — | Start of the red zone. Past it the scale prints red and the arc burns red. |
| `zones` | `{ from: number; to: number; color: NeonColor }[]` | — | Colored bands inside the scale. The band holding the value lights up. |
| `formatValue` | `(value: number) => string` | — | Formats the readout and aria-valuetext. |
| `color` | `NeonColor` | `inherited` | Palette name or hex for the needle, arc and readout. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 160, 224 or 288px across. |
## Accessibility
- The root has role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and aria-valuetext (the formatted value and unit).
- The dial itself is hidden from screen readers; the meter's value is the single source of truth.
- The needle, arc and readout are driven by a spring outside React rendering. Under reduced motion they jump straight to the value.
## Source
`components/ui/gauge.tsx`
```tsx
"use client";
import * as React from "react";
import { useMotionValueEvent, useReducedMotion, useSpring } from "motion/react";
import { cn } from "@/lib/utils";
import { neonVars, toNeonRgb, type NeonColor } from "@/lib/neon";
// Small dials print larger (in dial units) so the legends stay readable. `px` is rendered
// pixels per dial unit, used to keep numerals from shrinking below a readable 7.5px.
const sizes = {
sm: { root: "w-40", legend: 10, numeral: 12, px: 0.8 },
md: { root: "w-56", legend: 8, numeral: 10.5, px: 1.12 },
lg: { root: "w-72", legend: 7.5, numeral: 10, px: 1.44 },
} as const;
// Rough advance of a tabular numeral (or the minus sign) in em, with room for the gap between labels.
const NUMERAL_EM = 0.72;
// The dial is drawn in a 200-unit box and sweeps 240°, leaving the bottom for the readout.
const SWEEP = 240;
const ARC_R = 87;
const RED = "255 77 94";
const CORE = "color-mix(in srgb, rgb(var(--neon)) 30%, white)";
const RED_CORE = `color-mix(in srgb, rgb(${RED}) 35%, white)`;
const NEEDLE = "M100 30 L102.8 100 L101.8 117 L98.2 117 L97.2 100 Z";
function clamp(value: number, lower: number, upper: number) {
return Math.min(upper, Math.max(lower, value));
}
function decimalsOf(value: number) {
return Math.min(2, (String(value).split(".")[1] ?? "").length);
}
function polar(angle: number, radius: number) {
const rad = ((angle - 90) * Math.PI) / 180;
return [100 + radius * Math.cos(rad), 100 + 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;
return `M${x1.toFixed(2)} ${y1.toFixed(2)}A${radius} ${radius} 0 ${large} 1 ${x2.toFixed(2)} ${y2.toFixed(2)}`;
}
// Printed scales use a true minus sign, not a hyphen.
const minus = (text: string) => text.replace(/^-/, "\u2212");
function trim(value: number) {
return minus(String(Number(value.toFixed(2))));
}
export type GaugeZone = { from: number; to: number; color: NeonColor };
export interface GaugeProps extends Omit, "color" | "children"> {
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
size?: keyof typeof sizes;
value: number;
min?: number;
max?: number;
/** Legend printed on the dial. Also names the meter. */
label?: string;
/** Printed under the readout and read after the value. */
unit?: string;
/** Number of numbered intervals on the scale. */
ticks?: number;
/** Everything from here to max is the red zone: printed red, and the arc burns red past it. */
redline?: number;
/** Colored bands printed inside the scale. The band holding the value lights up. */
zones?: GaugeZone[];
/** Formats the readout and the value read to screen readers. */
formatValue?: (value: number) => string;
}
const Gauge = React.forwardRef(
(
{
className,
style,
color,
size = "md",
value: valueProp,
min = 0,
max = 100,
label,
unit,
ticks = 10,
redline,
zones,
formatValue,
"aria-label": ariaLabel,
...props
},
ref,
) => {
const uid = React.useId().replace(/[^a-zA-Z0-9_-]/g, "");
const s = sizes[size];
const reduceMotion = useReducedMotion();
const value = clamp(valueProp, min, max);
const range = max - min || 1;
const decimals = decimalsOf(value);
const format = (v: number) => {
const shown = Number(v.toFixed(decimals));
return formatValue ? formatValue(shown) : minus(shown.toFixed(decimals));
};
const fraction = (v: number) => (clamp(v, min, max) - min) / range;
const angleOf = (v: number) => -SWEEP / 2 + fraction(v) * SWEEP;
const red = redline !== undefined && redline < max ? clamp(redline, min, max) : undefined;
// The spring drives the needle, the lit arc and the readout through direct
// DOM writes. React renders the first value only, so it never fights the spring.
const spring = useSpring(value, { stiffness: 150, damping: 13, mass: 1 });
const [initial] = React.useState(value);
const needleRef = React.useRef(null);
const shadowRef = React.useRef(null);
const arcRefs = React.useRef<(SVGPathElement | null)[]>([]);
const redRefs = React.useRef<(SVGPathElement | null)[]>([]);
const maskRef = React.useRef(null);
const readoutRef = React.useRef(null);
const draw = (v: number) => {
const angle = angleOf(v);
needleRef.current?.setAttribute("transform", `rotate(${angle.toFixed(2)} 100 100)`);
shadowRef.current?.setAttribute("transform", `translate(1.5 3) rotate(${angle.toFixed(2)} 100 100)`);
const lit = red === undefined ? fraction(v) : Math.min(fraction(v), fraction(red));
for (const path of arcRefs.current) path?.setAttribute("stroke-dasharray", `${(lit * 1000).toFixed(1)} 1000`);
maskRef.current?.setAttribute("stroke-dasharray", `${(fraction(v) * 1000).toFixed(1)} 1000`);
if (red !== undefined) {
const over = clamp((v - red) / (max - red || 1), 0, 1);
for (const path of redRefs.current) path?.setAttribute("stroke-dasharray", `${(over * 1000).toFixed(1)} 1000`);
}
if (readoutRef.current) readoutRef.current.textContent = format(v);
};
const drawRef = React.useRef(draw);
React.useEffect(() => {
drawRef.current = draw;
// Props like min, max or formatValue may have changed what the current position means.
draw(spring.get());
});
React.useEffect(() => {
if (reduceMotion) spring.jump(value);
else spring.set(value);
}, [spring, value, reduceMotion]);
useMotionValueEvent(spring, "change", (v) => drawRef.current(v));
const start = -SWEEP / 2;
const end = SWEEP / 2;
const initialLit = red === undefined ? fraction(initial) : Math.min(fraction(initial), fraction(red));
const initialOver = red === undefined ? 0 : clamp((initial - red) / (max - red || 1), 0, 1);
const intervals = Math.max(0, Math.round(ticks));
const minorsPer = intervals > 10 ? 2 : 5;
const marks: { angle: number; major: boolean; value: number }[] = [];
if (intervals > 0) {
const count = intervals * minorsPer;
for (let i = 0; i <= count; i++) {
const v = min + (i / count) * range;
marks.push({ angle: angleOf(v), major: i % minorsPer === 0, value: v });
}
}
// Fit the numerals to the room between them: shrink first, and once they would drop below a
// readable size, number every 2nd (3rd, …) major tick instead, preferring a step that still
// numbers the last one.
const majors = marks.filter((mark) => mark.major);
const spacing = intervals > 0 ? ((SWEEP / intervals) * Math.PI * 54) / 180 : 0;
const longest = Math.max(1, ...majors.map((mark) => trim(mark.value).length));
const fitFor = (step: number) => (spacing * step * 0.75) / (longest * NUMERAL_EM);
const floor = Math.max(7, 7.5 / s.px);
const steps = Array.from({ length: Math.max(1, intervals) }, (_, i) => i + 1).filter((step) => fitFor(step) >= floor);
const step = steps.find((n) => intervals % n === 0) ?? steps[0] ?? Math.max(1, intervals);
const numeralSize = clamp(fitFor(step), floor, s.numeral);
const numerals = majors.filter((_, i) => i % step === 0);
// Long legends ("×1000 r/min") shrink to stay between the end numerals.
const legendSize = label ? Math.min(s.legend, 68 / (label.length * 0.9)) : s.legend;
const isRed = (v: number) => red !== undefined && v >= red - 1e-9;
const activeZone = zones?.findIndex((zone) => value >= Math.min(zone.from, zone.to) && value <= Math.max(zone.from, zone.to));
const text = format(value);
const maskId = `nk-gauge-${uid}-ticks`;
return (
{/* Bezel, face and printed scale */}
{/* Everything that is lit: the arc, the ticks it has passed, and the readout */}
{/* Past the redline the arc burns red */}
{red !== undefined && (
)}
{/* The needle floats over the face and throws a shadow on it */}
{/* Glass over the dial */}