GaugeChart

One KPI against its range or goal, as a ring or a 270° arc.

stable

Quick Preview

Occupancy

Units let this month

Collection rate

Target 80%

Listings published

Quarterly goal

Usage

import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
import { GaugeChart } from "@giddaa-housing/ui/gauge-chart";

<ChartCard size="sm" className="items-center">
  <ChartHeader className="self-stretch"><ChartTitle>Collection rate</ChartTitle></ChartHeader>
  <GaugeChart
    value={72}
    target={80}
    status="auto"
    caption="of target"
    formatValue={(value) => `${value}%`}
    ariaLabel="Collection rate 72% against an 80% target"
  />
</ChartCard>

GaugeChart takes scalar props, not a data array. The value is clamped to [min, max] (0–100 by default). variant="ring" is a full circle from twelve o'clock and variant="arc" a 270° gauge open at the bottom. A target adds a tick across the track, and status="auto" colors the arc success when the value meets the target and warning when it falls short. The center shows formatValue(value) when given, otherwise the share of the range as a percentage.

Examples

KPI rings

A plain reading, a reading against a target with status="auto", and a custom label, max, and color.

Occupancy

Units let this month

Collection rate

Target 80%

Listings published

Quarterly goal

Arc

Rent collected

October target ₦48M

<GaugeChart
  variant="arc"
  size="lg"
  value={41_500_000}
  max={50_000_000}
  target={48_000_000}
  status="auto"
  caption="Collected"
  formatValue={(value) => naira.format(value)}
  ariaLabel="Rent collected ₦41.5M against a ₦48M target"
/>

Props

Prop/APITypeDefaultDescription
valuenumberrequiredReading, clamped to [min, max].
ariaLabelstringrequiredAccessible name; state the value and any target.
min, maxnumber0, 100Range of the scale.
targetnumber-Goal, drawn as a tick across the track.
status"auto"-Success when the value meets target, warning otherwise.
variant"ring" | "arc""ring"Full circle or 270° arc.
size"sm" | "md" | "lg"inherited, otherwise "md"Diameter, thickness, and type (GAUGE_CHART_LAYOUT).
labelstring | number | falseformatted value, or percent of rangeCenter headline; false hides it.
captionstring-Caption under the headline.
colorCSS colorchart-1Progress arc color when status is not set.
namestring"Value"Tooltip row label.
tooltipbooleantrueHover and keyboard tooltip.
formatValue(value: number) => string-Headline and tooltip formatting.
emptyMessageReactNode"No data to display"Shown when value is not a finite number.
Chart host propssee Chart-initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
createGaugeChartDefinition(options)function-Same options; returns an extensible TanStack definition.

Accessibility

  • The ariaLabel is the main accessible output; include the value, unit, and target.
  • status="auto" uses color for success and warning; keep a caption or nearby text that states whether the target was met.
  • Use one gauge per KPI; compare several values with a bar chart instead.

On this page