Component

Radial Gauge

A circular progress / gauge component that maps a numeric value to a proportional arc. Supports semantic zone colouring (success / warning / danger), configurable center labels, and three sizes — ideal for score cards, interview report rings, and dashboard KPIs.

Basic

Pass a value between min (0) and max (100). The arc length and center number update automatically. Add a sublabel to annotate the unit.

With zones / thresholds

Pass a zones array to colour the arc based on where the value falls. Zones are sorted internally; the first zone whose upTo ≥ value wins. Use the slider to see the colour change live.

Adjust value45

Sizes

Three sizes are available: sm (80 px), md (120 px, default), and lg (160 px). Font sizes for labels scale with the ring.

Installation

$pnpm add @refraction-ui/react

Usage

tsx

import { RadialGauge } from '@refraction-ui/react'

export function ScoreCard() {
  return (
    <RadialGauge
      value={78}
      sublabel="Score"
      zones={[
        { upTo: 33, tone: 'danger' },
        { upTo: 66, tone: 'warning' },
        { upTo: 100, tone: 'success' },
      ]}
      aria-label="78 out of 100"
    />
  )
}

Props

Prop	Type	Default	Description
`value`	`number`	--	Current gauge value (required).
`min`	`number`	`0`	Minimum possible value.
`max`	`number`	`100`	Maximum possible value.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Visual size of the gauge (80 / 120 / 160 px diameter).
`thickness`	`number`	`8`	Stroke thickness of the track and arc in pixels.
`label`	`React.ReactNode`	--	Primary center label. Overrides the default numeric value display.
`sublabel`	`React.ReactNode`	--	Secondary label rendered below the primary label.
`zones`	`GaugeZone[]`	--	Threshold zones that colour the arc: `{ upTo: number; tone: "default"\|"success"\|"warning"\|"danger" }[]`. Sorted internally; first zone whose `upTo >= value` wins.
`showValue`	`boolean`	`true`	Show the numeric value in the center when no explicit label is provided.
`aria-label`	`string`	--	Accessible name for the gauge (`role="meter"`).
`className`	`string`	--	Additional CSS classes applied to the SVG element.