Installation
pnpm dlx shadcn@latest add https://dithercn.dev/r/gauge.jsonUsage
import { Gauge } from "@/components/dithercn/gauge";
export function CpuGauge({ load }: { load: number }) {
return <Gauge value={load} label="CPU load" unit="%" />;
}The arc is split into blocks over a faint track in the same colour. Blocks up to the value fill in, and the block at the value is solid and steps out by one cell, so the arc points at the reading like a needle. With fill="gradient" each block behind it is a step lighter; dotted, hatched and solid fill evenly.
Examples
Dials on a host card
variant="dial" sweeps 270°, like a speedometer. A gauge over 90% switches to color="red" with fill="hatched" and a low bloom, so it reads as a warning without relying on colour alone.
Ring beside a summary
variant="ring" is a full circle starting at the top, with the reading in the middle, here in green with fill="dotted". It hides the min and max labels, which would sit on top of each other.
Props
| Prop | Type | Default |
|---|---|---|
| value* The reading. Values outside min and max are clamped. | Type: number | Default – |
| label* What is measured. Shown under the value and used as the accessible name. | Type: string | Default – |
| min The start of the scale. | Type: number | Default 0 |
| max The end of the scale. | Type: number | Default 100 |
| variant A 180° arc, a 270° dial, or a full ring. | Type: "half" | "dial" | "ring" | Default "half" |
| size Width in CSS pixels. Text and ring thickness scale with it. | Type: number | Default 220 |
| segments How many blocks the arc is split into. The default depends on the variant. | Type: number | Default 28, 36 or 48 |
| unit Shown after the value, such as "%". | Type: string | Default "" |
| format How the value, min and max are formatted. | Type: Intl.NumberFormatOptions | Default { maximumFractionDigits: 1 } |
| showRange Show min and max under the ends of the arc. | Type: boolean | Default true, false for ring |
| color Colour of the filled blocks, a palette name or any CSS colour. | Type: DitherColor | Default "ink" |
| trackColor Colour of the empty track, drawn faint. | Type: DitherColor | Default color |
| fill Texture of the filled blocks. The block at the value is always solid. | Type: "gradient" | "dotted" | "hatched" | "solid" | Default "gradient" |
| bloom Soft glow in the fill's colour behind the filled blocks. | Type: "off" | "low" | "high" | Default "off" |
| animate Fill the blocks in one by one on mount. | Type: boolean | Default true |
| matrix Threshold pattern of the gradient fill. | Type: "bayer2" | "bayer4" | "bayer8" | "blue-noise" | Default "bayer4" |
| cell Size of one dither cell in CSS pixels. The ring thickness snaps to whole cells. | Type: number | Default --dither-cell |
Notes
- The gauge has
role="meter"witharia-valuenow,aria-valuemin,aria-valuemaxand anaria-valuetextthat includes the unit. The drawing is hidden from assistive technology. - Blocks fade in one after another when the gauge appears or the value rises. With reduced motion turned on they appear at once.
- It is plain SVG with one pattern per density, so it costs nothing after it renders. Bloom is a blurred copy of the filled blocks.