tremor-gauge

Gauge chart components for the Tremor design system. Pure SVG rendering with zero charting dependencies.

Live Examples | npm | GitHub

• GaugeChart — Single-value arc gauge with optional needle, thresholds, and gradient fills
• GaugeMulti — Multi-segment gauge with interactive segments and tooltips
• GaugeLegend — Legend companion with colored indicators, values, and share badges

Install

npm install tremor-gauge

Peer dependencies: react and react-dom (18 or 19).

Tailwind CSS Setup

Add the library to your Tailwind content config so its classes are included:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/tremor-gauge/dist/**/*.{js,cjs}",
  ],
  darkMode: "class",
};

Dark mode is supported via Tailwind's class strategy.

Usage

import { GaugeChart, GaugeMulti, GaugeLegend } from "tremor-gauge";

Single gauge with needle

<GaugeChart
  value={72}
  color="blue"
  label="Performance"
  showNeedle
  arcSpan={240}
  valueFormatter={(v) => `${v}%`}
/>

Threshold zones

<GaugeChart
  value={67}
  min={20}
  max={100}
  showNeedle
  arcSpan={270}
  thresholds={[
    { value: 20, color: "emerald" },
    { value: 70, color: "amber" },
    { value: 85, color: "pink" },
  ]}
  showThresholdArc="bands"
/>

Gradient fill

<GaugeChart
  value={92}
  gradient={{ from: "cyan", to: "blue" }}
  label="Score"
  strokeWidth={14}
/>

Multi-segment gauge with synced legend

const [active, setActive] = useState<string | undefined>();

const data = [
  { name: "Sales", amount: 450 },
  { name: "Returns", amount: 120 },
];
const colors = ["blue", "emerald"];
const items = data.map((d, i) => ({
  name: d.name,
  value: d.amount,
  color: colors[i],
}));

<GaugeMulti
  data={data}
  category="name"
  value="amount"
  colors={colors}
  label="Total"
  activeName={active}
  onValueChange={(d) => setActive(d ? d.name : undefined)}
/>
<GaugeLegend
  items={items}
  showShare
  activeName={active}
  onItemClick={(name) => setActive(active === name ? undefined : name)}
/>

Clicking a segment highlights the matching legend item and vice versa.

GaugeChart Props

Prop	Type	Default	Description
value	number	required	Current value
min	number	0	Minimum value
max	number	100	Maximum value
color	Color	"blue"	Tremor color token (ignored when thresholds or gradient is set)
thresholds	GaugeThreshold[]	—	Value-based color zones (see below)
showThresholdArc	boolean | "bands" | "ticks"	false	Visualise threshold zones on the track
gradient	{ from: Color; to: Color }	—	Gradient fill across the arc
valueFormatter	(v: number) => string	String	Format the center value label
showLabel	boolean	true	Show center value label
label	string	—	Secondary label text below the value
showMinMax	boolean	false	Show min/max labels at arc ends
showAnimation	boolean	true	Animate arc and needle on mount
arcSpan	180 | 240 | 270	180	Arc span in degrees
showNeedle	boolean	false	Show needle indicator
strokeWidth	number	10	Arc stroke width
className	string	—	Additional CSS class

GaugeThreshold

{ value: number; color: Color }

Each entry defines a zone starting at value. The fill color changes to the highest threshold the current value has reached.

GaugeMulti Props

Prop	Type	Default	Description
data	object[]	required	Data array
category	string	required	Key for category labels
value	string	required	Key for numeric values
colors	Color[]	all colors	Color tokens per segment
label	string	—	Center label text
showTooltip	boolean	true	Show tooltip on hover
onValueChange	(datum | null) => void	—	Segment click callback
activeName	string	—	Externally controlled highlighted segment name
customTooltip	(props) => ReactNode	—	Custom tooltip renderer
valueFormatter	(v: number) => string	String	Format values in tooltip and center label
marker	{ value, label? }	—	Marker line on the arc
arcSpan	180 | 240 | 270	180	Arc span in degrees
strokeWidth	number	12	Arc stroke width
showAnimation	boolean	true	Animate segments on mount
className	string	—	Additional CSS class

GaugeLegend Props

Prop	Type	Default	Description
items	GaugeLegendItem[]	required	Legend items
valueFormatter	(v: number) => string	String	Format values
showShare	boolean	false	Show percentage share badge
activeName	string	—	Highlighted item name
onItemClick	(name: string) => void	—	Item click callback
className	string	—	Additional CSS class

Colors

9 Tremor-compatible tokens: blue, emerald, violet, amber, gray, cyan, pink, lime, fuchsia (all at 500 shade).

Features

• Pure SVG via <circle> stroke-dasharray — no canvas, no charting library
• Animate on mount with CSS transitions (respects prefers-reduced-motion)
• Dark mode via Tailwind dark: classes
• Accessible: role="meter" with aria-valuenow/min/max
• "use client" directive for Next.js App Router compatibility
• Fluid sizing via SVG viewBox — control width with className

Development

npm install
npm test          # Run Vitest tests
npm run build     # Build ESM + CJS + types
npm run storybook # Interactive component demos
npm run typecheck # TypeScript check

License

Apache-2.0