Skip to the content

Charts

radial-progress

A ring gauge for one value against a limit, with the value and a label in the centre.

Charts

When to use it

One ratio: a quota used, a score, a goal reached. Size it with a width class (w-32 by default). For several ratios side by side use a list of bars (bar-chart horizontal), not a ring each; for parts of a whole use donut-chart.

See it working

The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Charts page.

Line chart

  • Requests
  • Errors
Example: requests and errors per day
dayRequestsErrors
Mar 1, 202612056
Mar 2, 202618076
Mar 3, 202615052
Mar 4, 202621088
Mar 5, 202626072
Mar 6, 2026240100
Mar 7, 202630084
Mar 8, 2026280120
Mar 9, 202634096
Mar 10, 2026390112
Mar 11, 2026370140
Mar 12, 2026430124

Area chart, stacked

  • Images
  • Video
  • Audio
Example: storage used per month, by kind
monthImagesVideoAudio
Jan 1, 202612306
Feb 1, 202618429
Mar 1, 2026226111
Apr 1, 2026277016
May 1, 2026358418

Bar chart

  • Web
  • App
Example: orders by channel per quarter
quarterWebApp
Q1320210
Q2410290
Q3380350
Q4460420

Donut chart

Example: traffic by source
sourcevisitsShare
Search5,20049%
Direct3,10029%
Referral1,40013%
Social9008%
  • Search5,200 · 49%
  • Direct3,100 · 29%
  • Referral1,400 · 13%
  • Social900 · 8%

Heatmap

Example: sessions by day and hour
day0910111213141516
Mon61116212681318
Tue13192581420269
Wed202711182591623
Thu271220281321614
Fri112061524101928

Radial progress, sparkline, stat

72%Storage used

Signups

1,204

+12%than last week

Add it

npx shadcn@latest add @rivier-ui/radial-progress

The registry is named once in components.json: see Installation.

Example

Import it from @/components/viz/radial-progress.

<RadialProgress value={72} label="Storage used" />
<RadialProgress value={3} max={5} label="Steps done" formatValue={(value) => `${value} of 5`} className="w-40" />

What it needs

A client component: it uses state, effects or browser behaviour. No packages beyond React.

It imports

Source

The whole file. Once copied it is yours: the registry item holds the same text.

src/components/viz/radial-progress.tsx
"use client";
/**
 * @name radial-progress
 * @category viz
 * @description A ring gauge for one value against a limit, with the value and a label in the centre.
 * @when One ratio: a quota used, a score, a goal reached. Size it with a width class (`w-32` by default). For several ratios side by side use a list of bars (bar-chart horizontal), not a ring each; for parts of a whole use donut-chart.
 * @example
 * <RadialProgress value={72} label="Storage used" />
 * <RadialProgress value={3} max={5} label="Steps done" formatValue={(value) => `${value} of 5`} className="w-40" />
 */
import type { ComponentProps, CSSProperties, ReactNode } from "react";
import { cn } from "@/lib/cn";
import { chartSeries, formatNumber } from "@/components/viz/chart";

export type RadialProgressProps = Omit<ComponentProps<"div">, "children"> & {
  value: number;
  min?: number;
  max?: number;
  /** What is measured. Shown under the value, and the gauge's accessible name. */
  label: string;
  /** The text in the centre. Default: the share of the range as a percentage. */
  formatValue?: (value: number) => string;
  /** A BCP 47 locale for the default percentage. Default "en-US". */
  locale?: string;
  /** Ring thickness, as a percentage of the gauge's width. */
  thickness?: number;
  /** The ends of the filled arc. */
  cap?: "round" | "butt";
  /** Which series colour, 0-based. Default 0, the highlight. */
  series?: number;
  /** Replaces the centre (the value and the label) with your own content. */
  children?: ReactNode;
};

/**
 * A client component although it holds no state: it calls helpers from chart, which is a client module, and a
 * server component cannot call a client module's functions.
 */
export function RadialProgress({ value, min = 0, max = 100, label, formatValue, locale, thickness = 8, cap = "round", series = 0, children, className, ...props }: RadialProgressProps) {
  const span = max - min;
  const share = span > 0 && Number.isFinite(value) ? Math.max(0, Math.min(1, (value - min) / span)) : 0;
  const text = formatValue ? formatValue(value) : formatNumber(share, locale, { style: "percent", maximumFractionDigits: 0 });
  const stroke = Math.max(1, Math.min(30, thickness));
  const radius = 50 - stroke / 2;
  const length = 2 * Math.PI * radius;
  const style = chartSeries(series);

  return (
    <div
      data-slot="radial-progress"
      role="meter"
      aria-label={label}
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={Number.isFinite(value) ? Math.max(min, Math.min(max, value)) : min}
      aria-valuetext={text}
      className={cn("relative aspect-square w-32", className)}
      {...props}
    >
      <svg aria-hidden="true" viewBox="0 0 100 100" className="block size-full -rotate-90">
        {/* The track is the same colour, fainter, so the ring reads as one thing. */}
        <circle cx={50} cy={50} r={radius} fill="none" className={style.stroke} strokeOpacity={0.16} strokeWidth={stroke} />
        {share > 0 ? (
          <circle
            cx={50}
            cy={50}
            r={radius}
            fill="none"
            // The arc is one dash as long as the circle, shifted back by what is not filled. It fills once on
            // mount by animating stroke-dashoffset, from the whole length (set as --rui-ring-length for the
            // rui-ring-in keyframes in the theme) to its place. stroke-dashoffset is a paint-only property: it
            // moves no layout, so it is the one exception here to "only transform and opacity". Under reduced
            // motion, and until those keyframes are in the stylesheet, the ring is simply drawn filled.
            className={cn(style.stroke, "motion-safe:animate-[rui-ring-in_var(--duration-scene)_var(--ease)_both]")}
            style={{ "--rui-ring-length": length } as CSSProperties}
            strokeWidth={stroke}
            strokeLinecap={cap}
            strokeDasharray={`${length} ${length}`}
            strokeDashoffset={length * (1 - share)}
          />
        ) : null}
      </svg>
      <div data-slot="radial-progress-center" className="absolute inset-0 flex flex-col items-center justify-center px-4 text-center">
        {children ?? (
          <>
            <span className="text-xl font-semibold text-foreground">{text}</span>
            <span className="text-xs text-muted-foreground">{label}</span>
          </>
        )}
      </div>
    </div>
  );
}