RadialGauge – Once UI

The RadialGauge component renders a tick-based circular or arc-shaped gauge that is ideal for health metrics, KPIs, and other real-time values. It supports full circles, semicircles, and custom arcs with configurable angles, direction, density, and visual health states.

Usage

72%

<RadialGauge
  width={260}
  height={260}
  value={72}
  unit="%"
/>

Hue

Use the hue prop to quickly change the color ramp of active ticks to represent different states.

Hue

82%

56%

28%

90%

<RadialGauge
  width={260}
  height={260}
  value={82}
  unit="%"
  hue="success"
/>
<RadialGauge
  width={260}
  height={260}
  value={56}
  unit="%"
  hue="neutral"
/>
<RadialGauge
  width={260}
  height={260}
  value={28}
  unit="%"
  hue="danger"
/>
<RadialGauge
  width={260}
  height={260}
  value={90}
  unit="%"
  hue={[0, 200]}
/>

Angles

You can create semicircular or arc gauges by combining angle and edgePad. The angle system is intuitive:

0° = left
90° = top
180° = right
270° = bottom

Angles

68%

<RadialGauge
  width={300}
  height={150}
  value={68}
  line={{
    count: 24,
  }}
  angle={{
    start: 0,
    sweep: 180,
  }}
>
  <Row fill vertical="end" horizontal="center" padding="20">
    <Text variant="heading-strong-xl">68%</Text>
  </Row>
</RadialGauge>

Ticks

Control how many ticks are rendered and how long they are using lineCount, lineWidth, and lineLength.

Density

42ms

<RadialGauge
  width={320}
  height={320}
  value={42}
  unit="ms"
  line={{
    count: 80,
    width: 2,
    length: 32,
  }}
/>

Animation

For interactive demos or dashboards, you can animate the value over time on the client. The example below simulates accelerating and braking.

Animated speed meter

4km/h

"use client";

import React, { useEffect, useState } from "react";
import { Column, Text } from "@once-ui-system/core";
import { RadialGauge } from "@once-ui-system/core/data";

export function RadialGaugeSpeedDemo() {
const [value, setValue] = useState(20);
const [phase, setPhase] = useState<"idle" | "accelerate" | "brake">("idle");

useEffect(() => {
  let timeout: ReturnType<typeof setTimeout> | undefined;
  let interval: ReturnType<typeof setInterval> | undefined;

  const startAccelerate = () => {
    setPhase("accelerate");
    interval = setInterval(() => {
      setValue(prev => {
        const next = Math.min(prev + 6, 96);
        if (next >= 96) {
          clearInterval(interval);
          timeout = setTimeout(startBrake, 600);
        }
        return next;
      });
    }, 90);
  };

  const startBrake = () => {
    setPhase("brake");
    interval = setInterval(() => {
      setValue(prev => {
        const next = Math.max(prev - 8, 18);
        if (next <= 18) {
          clearInterval(interval);
          timeout = setTimeout(startAccelerate, 800);
        }
        return next;
      });
    }, 90);
  };

  timeout = setTimeout(startAccelerate, 400);

  return () => {
    if (interval) clearInterval(interval);
    if (timeout) clearTimeout(timeout);
  };
}, []);

const label = phase === "accelerate" ? "Accelerating" : phase === "brake" ? "Braking" : "Idle";

return (
  <Column center gap="8">
    <RadialGauge
      width={260}
      height={260}
      value={value}
      unit="km/h"
      angle={{
        start: -120,
        sweep: 240,
      }}
      edgePad={4}
    />
    <Text variant="label-default-m" onBackground="neutral-medium">
      {label}
    </Text>
  </Column>
);
}

Props

The RadialGauge component accepts all layout props from Column (except direction) plus the following gauge-specific props:

	Type	Default
width Overall width, in pixels.	number	300
height Overall height, in pixels.	number	300
line The tick marks around the arc: how many, how thick, how long.	{ count?: number; width?: number; length?: number; }	—
unit Rendered after the value — a percent sign, a unit, anything.	React.ReactNode	—
value Where the gauge reads, 0–100.	number	7
angle Where the arc starts and how far it sweeps, in degrees. 360 is a full ring.	{ start: number; sweep: number; }	{ start: 0, sweep: 360, }
direction Which way the sweep runs from the start angle.	cwccw	cw
edgePad Inset between the arc and the edge of the box, in pixels.	number	0
children Rendered in the middle of the gauge, in place of the value.	React.ReactNode	—
hue Colour the arc by its value — a named ramp, or a [from, to] pair of hue degrees to interpolate between.	successneutraldanger[number, number]	—
color A single colour for the arc, when it should not vary with the value. Takes a token or any CSS colour.	ColorValue	contrast
…and every FlexProps prop	inherited	—

Use RadialGauge when you need a compact, highly legible representation of a single metric that can be scanned quickly, such as system health, SLO burn rate, or real-time utilization.