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/API | Type | Default | Description |
|---|---|---|---|
value | number | required | Reading, clamped to [min, max]. |
ariaLabel | string | required | Accessible name; state the value and any target. |
min, max | number | 0, 100 | Range of the scale. |
target | number | - | 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). |
label | string | number | false | formatted value, or percent of range | Center headline; false hides it. |
caption | string | - | Caption under the headline. |
color | CSS color | chart-1 | Progress arc color when status is not set. |
name | string | "Value" | Tooltip row label. |
tooltip | boolean | true | Hover and keyboard tooltip. |
formatValue | (value: number) => string | - | Headline and tooltip formatting. |
emptyMessage | ReactNode | "No data to display" | Shown when value is not a finite number. |
| Chart host props | see Chart | - | initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style. |
createGaugeChartDefinition(options) | function | - | Same options; returns an extensible TanStack definition. |
Accessibility
- The
ariaLabelis the main accessible output; include the value, unit, and target. status="auto"uses color for success and warning; keep acaptionor nearby text that states whether the target was met.- Use one gauge per KPI; compare several values with a bar chart instead.