Gauge

Installation

pnpm dlx shadcn@latest add @bklit/gauge-chart

Usage

Gauge draws notches around an arc (default) or along a horizontal track (orientation="linear"). The center label is optional — omit centerValue for a track-only gauge.

• Fill vs center: value is the fill level 0–100. centerValue is the statistic shown in the label (often the same story or a related KPI).
• Arc center: arc gauges overlay the label in the middle of the sweep (PieCenter-style NumberFlow + caption).
• Linear label placement: with orientation="linear", place the label above or below the track using labelPlacement (top | bottom) and labelAlign (start | center | end) — the same six-position model as chart legend (top/bottom × left/center/right).
• Responsive: omit width and height to fill the parent. Arc gauges use minWidth (default 300) and an aspect ratio. Linear gauges fill the parent width and use linearHeight (default 24).
• Linear notches: linear gauges default to uniformWidth (rectangular notches). Pass uniformWidth={false} for tapered ticks.
• Patterns / gradients in <defs>: pass PatternLines, LinearGradient, etc. as children, then set activeFill / inactiveFill to url(#id).
• Arc gradients: set useGradient. Optional activeGradient and inactiveGradient are [hexFrom, hexTo] tuples (interpolated along the notch index).
• Fill opacity: activeFillOpacity and inactiveFillOpacity map to SVG fill-opacity (0–1). Defaults are 1 for active notches and 0.8 for the track; docs and gallery examples use inactiveFillOpacity={0.4} for a lighter track.
• Corner radius: notchCornerRadius is the fillet in pixels at each notch corner (0 = sharp). Large values are clamped by edge length and radial depth so shapes can approach a capsule / near-circular look.

import { Gauge, PatternLines } from "@bklitui/ui/charts";

export default function RevenueGauge() {
  return (
    <Gauge
      value={66}
      centerValue={428_000}
      spacing={25}
      inactiveFillOpacity={0.4}
      defaultLabel="ARR run rate"
      formatOptions={{
        style: "currency",
        currency: "USD",
        maximumFractionDigits: 0,
      }}
    />
  );
}

Linear gauge

Track-only (no label):

<Gauge
  orientation="linear"
  value={72}
  totalNotches={72}
  spacing={0}
  notchCornerRadius={3}
  inactiveFillOpacity={0.4}
  useGradient
/>

With label below center:

<Gauge
  orientation="linear"
  value={72}
  centerValue={428_000}
  defaultLabel="ARR run rate"
  labelPlacement="bottom"
  labelAlign="center"
  totalNotches={72}
  spacing={0}
  notchCornerRadius={3}
  inactiveFillOpacity={0.4}
  useGradient
/>

Props

Gauge

Theming

Inactive (track) notches default to var(--border) — shared with ring tracks and radar grid lines. Active notches default to var(--chart-1). Override with inactiveFill / activeFill, or tune --border / --chart-1 in your theme. See Theming.

Live examples

See the Gauge gallery for arc and linear variants. Use Studio to tune every gauge prop interactively — toggle Linear for the horizontal notch track, Show label for optional center text, and the legend-style Position picker for label placement — then copy the resulting code.