Gauge React chart component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Gauge is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Gauge from @/components/ui/gauge.

import { Gauge } from "@/components/ui/gauge"

export function SalesGoal() {
  return (
    <Gauge
      value={67.6}
      valueFormat="percent"
      target={75}
      thresholds={[
        { value: 0, tone: "danger", label: "Behind" },
        { value: 50, tone: "warning", label: "Close" },
        { value: 75, tone: "success", label: "Good" },
      ]}
      label="Monthly sales goal"
      description="$6,760 of $10,000"
      locale="en-US"
    />
  )
}

Props

• value*default 67.6
  number | null

  The current value. Outside min..max it is clamped for drawing, the text still shows the real number. null draws the track only and a dash.

• mindefault 0
  number

  Start of the scale. min >= max renders the empty state (with a warning in development).

• maxdefault 100
  number

  End of the scale.

• variantdefault "arc"
  "arc" | "needle" | "segments"

  arc fills the track up to the value; needle is a thin zone-colored track with a needle; segments cuts the track into zones (the current one solid, the rest at 25%, a ring marker at the value) or, with a segments count, into equal steps that light up.

• sweepdefault "240"
  180 | 240 | 270

  Degrees of the dial, symmetric around 12 o'clock. 180 is a half circle, 270 an open ring.

• sizedefault "md"
  "sm" | "md" | "lg"

  Width 120 / 200 / 280px (the dial shrinks with a narrower container) and the value 18 / 28 / 40px.

• thicknessdefault 0
  number

  Track width in px. Auto is 10% of the width (12 / 20 / 28px), 4px for the needle track.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The arc color when no zone applies (no thresholds, colorByZone off, or a value below the first zone). neutral is the foreground ink.

• colordefault ""
  string

  Any css color, a palette slot ("series-3") or a tone name. Replaces the tone; zones still win while colorByZone is on.

• thresholds
  { value: number; tone: Tone; label?: string }[]

  Zone starts, in any order (they are sorted): each zone runs from its value to the next one or max. Labels name the zone in the chip and the spoken text. Lower is better? List them success, warning, danger.

• colorByZonedefault true
  boolean

  The arc and the chip take the tone of the zone the value is in.

• showBandsdefault true
  boolean

  A thin 3px zone band outside the arc (arc variant with thresholds); the zones the value is not in fade back.

• segmentsdefault 0
  number

  Equal steps for the segments variant that light up to the value (tinted by their zone when there are thresholds). Auto is one segment per zone, or 10 steps without thresholds.

• targetdefault 0
  number

  A tick across the track, cut into the surface so it reads over any color, and part of the spoken text. Hidden outside min..max. No default: without it there is no tick (the playground's 0 places it at 75 % of the range).

• roundCapsdefault true
  boolean

  Rounded arc ends (segment corners get a 4px radius). Off gives square ends.

• labeldefault ""
  ReactNode

  Under the value, e.g. "Monthly goal". A string also names the meter; other nodes label it through aria-labelledby.

• descriptiondefault ""
  ReactNode

  Under the label in muted text, e.g. "$6,760 of $10,000". Linked with aria-describedby.

• showValuedefault true
  boolean

  The big number in the bowl.

• showMinMaxdefault true
  boolean

  The scale ends under the arc ends, compact for big numbers ("$190K").

• showZonedefault true
  boolean

  A small chip in the zone's tone with its label, when the current zone has one.

• valueFormatdefault "number"
  ChartValueFormat ("number" | "compact" | "currency" | "percent")

  How the value and the scale ends print. percent takes whole numbers: 67.6 is "67,6 %".

• currencydefault "USD"
  string

  ISO 4217 code for valueFormat="currency", with its narrow symbol ("$", "€").

• decimalsdefault 0
  number

  Fraction digits of the value. Unset (Auto in the playground) keeps the final value's digits all through the count (67.6 counts in tenths, 42 in whole numbers).

• formatValue
  (value: number, context: { kind: "value" | "tick" | "label" }) => string

  Full control over the text, e.g. v => `${v.toLocaleString("en-US")} h`. value is called on every frame of the count, tick for min / max, label for the spoken text.

• localedefault ""
  string

  Intl locale for every number. Empty follows the UIProvider, then the page.

• surfacedefault ""
  string

  The color behind the gauge: the target notch and the segment marker are cut in it. Empty uses the surface token.

• animateddefault true
  boolean

  Sweeps and counts in the first time it scrolls into view, then glides between values. Off renders the final state (thumbnails, print).

• loadingdefault false
  boolean

  The chart kit's gauge skeleton and a placeholder for the value; the label stays.

• labels
  { target?: string; zone?: (label: string) => string; valueText?: (value, min, max, info) => string; empty?: string; loading?: string }

  The spoken text. Defaults: "target", "{label} zone", "No data", "Loading"; valueText replaces the whole aria-valuetext (info has the formatted text, zone and target).

• classNames
  Partial<Record<"dial" | "svg" | "track" | "band" | "arc" | "segment" | "needle" | "marker" | "target" | "content" | "value" | "label" | "description" | "zone" | "min" | "max", string>>

  Extra classes for the parts.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

More React chart and stat components