Overview

A circular progress indicator. The arc fills on a spring with a small knob riding its leading edge, and the centre number counts along with it. At 100% the ring turns green, a check draws in and a soft pulse goes out. indeterminate spins a breathing arc for unknown waits, sublabel adds a line under the value, and color tints the ring.


Installation

Use the CLI to install the component automatically:

$ pnpm dlx shadcn@latest add https://ui.sanjid.in/r/progress-ring.json

Install dependencies:

$ pnpm add motion

Add the utility function for class merging:

lib/utils.ts
tsx
import { ClassValue, clsx } from "clsx";import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {  return twMerge(clsx(inputs));}

Copy the component code into your project:

components/ui/progress-ring.tsx
tsx
"use client";
import React, { useEffect, useId, useRef, useState } from "react";import {  AnimatePresence,  animate,  motion,  useMotionValue,  useReducedMotion,  useTransform,} from "motion/react";import { cn } from "@/lib/utils";
export type ProgressRingProps = {  /** 0–100. Ignored when `indeterminate`. */  value?: number;  size?: number;  strokeWidth?: number;  /** Replaces the percentage in the centre. */  label?: string;  /** Small line under the centre value. */  sublabel?: string;  /** Spin an arc when progress is unknown. */  indeterminate?: boolean;  /** At 100%, turn green and show a check. */  showComplete?: boolean;  /** Ring colour. Any CSS colour; defaults to the ink colour. */  color?: string;  className?: string;  "aria-label"?: string;};
const SPRING = { type: "spring" as const, bounce: 0.1, duration: 0.8 };
export function ProgressRing({  value = 0,  size: sizeProp = 96,  strokeWidth: strokeWidthProp = 8,  label,  sublabel,  indeterminate = false,  showComplete = true,  color = "var(--color-ink)",  className,  "aria-label": ariaLabel,}: ProgressRingProps) {  const reduce = !!useReducedMotion();  const uid = useId().replace(/:/g, "");  const size = Number.isFinite(sizeProp) ? Math.max(24, sizeProp) : 96;  const stroke = Number.isFinite(strokeWidthProp) ? Math.max(1, Math.min(size / 4, strokeWidthProp)) : 8;  const clamped = Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : 0;  const complete = showComplete && !indeterminate && clamped >= 100;  const r = (size - stroke) / 2;  const cx = size / 2;
  const progress = useMotionValue(0);  const first = useRef(true);  useEffect(() => {    if (reduce) {      progress.set(clamped);      return;    }    // The first fill is slower so it reads as an entrance.    const controls = animate(progress, clamped, first.current ? { ...SPRING, duration: 1.2 } : SPRING);    first.current = false;    return () => controls.stop();  }, [clamped, progress, reduce]);
  const length = useTransform(progress, (v) => Math.max(0, v / 100));  const rounded = useTransform(progress, (v) => Math.round(v));  // A knob rides the leading end of the arc.  const angle = useTransform(progress, (v) => (v / 100) * 360 - 90);  const knobX = useTransform(angle, (a) => cx + r * Math.cos((a * Math.PI) / 180));  const knobY = useTransform(angle, (a) => cx + r * Math.sin((a * Math.PI) / 180));  const knobOpacity = useTransform(progress, [0, 2, 99, 100], [0, 1, 1, 0]);
  // One soft pulse when the ring completes.  const [pulse, setPulse] = useState(0);  const wasComplete = useRef(complete);  useEffect(() => {    if (complete && !wasComplete.current) setPulse((n) => n + 1);    wasComplete.current = complete;  }, [complete]);  const arcOpacity = useTransform(progress, (v) => (v < 0.5 ? 0 : 1));
  const ringColor = complete ? "#10b981" : color;  const fontSize = Math.max(11, size * 0.2);
  return (    <div      className={cn("relative inline-flex shrink-0 items-center justify-center", className)}      style={{ width: size, height: size }}      role="progressbar"      aria-label={ariaLabel ?? label ?? "Progress"}      aria-valuemin={indeterminate ? undefined : 0}      aria-valuemax={indeterminate ? undefined : 100}      aria-valuenow={indeterminate ? undefined : Math.round(clamped)}      aria-valuetext={indeterminate ? "Loading" : complete ? "Complete" : `${Math.round(clamped)}%`}    >      <svg width={size} height={size} className="overflow-visible">        <defs>          <linearGradient id={`${uid}-g`} x1="0" y1="0" x2="1" y2="1">            <stop offset="0" stopColor={ringColor} stopOpacity="0.55" />            <stop offset="1" stopColor={ringColor} />          </linearGradient>        </defs>        <circle cx={cx} cy={cx} r={r} fill="none" stroke="var(--color-rule)" strokeOpacity="0.8" strokeWidth={stroke} />
        {indeterminate ? (          <motion.circle            cx={cx}            cy={cx}            r={r}            fill="none"            stroke={`url(#${uid}-g)`}            strokeWidth={stroke}            strokeLinecap="round"            pathLength={1}            style={{ originX: "50%", originY: "50%" }}            animate={reduce ? { opacity: [1, 0.4, 1] } : { rotate: 360, strokeDasharray: ["0.1 1", "0.45 1", "0.1 1"] }}            transition={              reduce                ? { duration: 1.6, repeat: Infinity }                : { rotate: { duration: 1.2, repeat: Infinity, ease: "linear" }, strokeDasharray: { duration: 1.6, repeat: Infinity, ease: "easeInOut" } }            }          />        ) : (          <>            <motion.circle              cx={cx}              cy={cx}              r={r}              fill="none"              stroke={`url(#${uid}-g)`}              strokeWidth={stroke}              strokeLinecap="round"              transform={`rotate(-90 ${cx} ${cx})`}              style={{ pathLength: length, opacity: arcOpacity }}              className="transition-[stroke] duration-500"            />            <motion.circle              r={stroke * 0.32}              fill="var(--color-paper)"              style={{ cx: knobX, cy: knobY, opacity: knobOpacity }}            />            <AnimatePresence>              {pulse > 0 && !reduce ? (                <motion.circle                  key={pulse}                  cx={cx}                  cy={cx}                  r={r}                  fill="none"                  stroke={ringColor}                  strokeWidth={stroke}                  initial={{ opacity: 0.3, scale: 1 }}                  animate={{ opacity: 0, scale: 1.12 }}                  transition={{ duration: 0.6, ease: "easeOut" }}                  style={{ originX: "50%", originY: "50%" }}                />              ) : null}            </AnimatePresence>          </>        )}      </svg>
      <div className="absolute inset-0 flex flex-col items-center justify-center text-center">        <AnimatePresence initial={false} mode="popLayout">          {complete ? (            <motion.svg              key="done"              viewBox="0 0 24 24"              className="text-emerald-500"              style={{ width: size * 0.32, height: size * 0.32 }}              fill="none"              stroke="currentColor"              strokeWidth="2.6"              strokeLinecap="round"              strokeLinejoin="round"              initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.5 }}              animate={{ opacity: 1, scale: 1 }}              exit={{ opacity: 0, scale: 0.5 }}              transition={{ type: "spring", bounce: 0.4, duration: 0.5 }}            >              <motion.path d="M5 12.5l4.5 4.5L19 7.5" initial={{ pathLength: reduce ? 1 : 0 }} animate={{ pathLength: 1 }} transition={{ duration: 0.35, delay: 0.1 }} />            </motion.svg>          ) : (            <motion.div              key="value"              initial={{ opacity: 0, scale: 0.8, filter: "blur(4px)" }}              animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}              exit={{ opacity: 0, scale: 0.8, filter: "blur(4px)" }}              transition={{ duration: 0.25 }}              className="font-(family-name:--font-display) leading-none font-semibold tracking-[-0.02em] text-(--color-ink) tabular-nums"              style={{ fontSize }}              aria-hidden            >              {label ?? (indeterminate ? null : (                <>                  <motion.span>{rounded}</motion.span>                  <span className="text-[0.6em] font-medium text-(--color-neutral)">%</span>                </>              ))}            </motion.div>          )}        </AnimatePresence>        {sublabel ? (          <div className="mt-1 text-(--color-neutral)" style={{ fontSize: Math.max(10, size * 0.1) }} aria-hidden>            {sublabel}          </div>        ) : null}      </div>    </div>  );}

Adjust import paths according to your folder structure.


Basic Usage

tsx
import { ProgressRing } from "@/components/ui/progress-ring";
<ProgressRing value={progress} size={124} strokeWidth={10} sublabel="Uploading" aria-label="Upload" />
<ProgressRing value={72} size={56} strokeWidth={6} color="#6366f1" aria-label="Storage" />
<ProgressRing indeterminate size={56} aria-label="Syncing" />

Props

PropTypeRequiredDefaultDescription
valuenumberNo0Progress from 0 to 100.
size / strokeWidthnumberNo96 / 8Diameter and ring thickness in px.
labelstringNo—Replaces the percentage in the centre.
sublabelstringNo—Small line under the centre value.
indeterminatebooleanNofalseSpinning arc for waits of unknown length.
showCompletebooleanNotrueAt 100%, turn green and show a check.
colorstringNo"var(--color-ink)"Ring colour.
aria-label / classNamestringNo—Accessible name and wrapper classes.

Best Practices

  1. Always pass an aria-label saying what is progressing; the value is announced as a percentage, or as “Complete”.
  2. Turn off showComplete for gauges like storage or CPU that aren't tasks.
  3. Use indeterminate until you know the total, then switch to a value.
  4. Reduced motion jumps straight to the new value.