Progress Ring

Installation#

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/progress-ring.json

Manual

1. Install the dependencies

   npmpnpmbunyarn

   npm install clsx motion tailwind-merge

2. Add the shared helpers

   Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

   lib/motion.ts

   import type { Transition, Variants } from "motion/react";
   
   /** Durations in seconds. */
   export const duration = {
     instant: 0.1,
     quick: 0.18,
     base: 0.28,
     slow: 0.45,
   } as const;
   
   /** Cubic-bezier curves. */
   export const ease = {
     /** Entering, UI response. */
     out: [0.22, 1, 0.36, 1],
     /** Moving on screen. */
     inOut: [0.65, 0, 0.35, 1],
     /** Sheets and the mobile menu. */
     drawer: [0.32, 0.72, 0, 1],
   } as const;
   
   /** Everyday UI: presses, icon swaps, popovers and modals. Exits run at `exitFactor` of the enter. */
   export const ui = {
     press: { scale: 0.96, duration: 0.12 },
     icon: { type: "spring", duration: 0.3, bounce: 0 },
     popover: { duration: 0.18, ease: ease.out },
     modal: { duration: 0.24, ease: ease.out },
     exitFactor: 0.6,
   } as const;
   
   /** Once-per-visit motion on the landing page: hero letters, the reel and the afterimage. */
   export const kinetic = {
     heroLetter: { duration: 0.6, ease: ease.out },
     /** Delay per letter, eased so the wave slows toward the end. */
     heroStep: 0.035,
     reelSwap: { type: "spring", duration: 0.5, bounce: 0.1 },
     /** Two afterimages: lag in seconds and opacity of each. */
     ghost: { lag: [0.04, 0.09], opacity: [0.14, 0.06] },
   } as const;
   
   /** Spring presets. */
   export const spring = {
     snappy: { type: "spring", stiffness: 500, damping: 30 },
     smooth: { type: "spring", stiffness: 260, damping: 26 },
     bouncy: { type: "spring", stiffness: 300, damping: 15 },
   } as const satisfies Record<string, Transition>;
   
   /** Stagger between siblings, in seconds (0.03–0.06). */
   export const stagger = {
     tight: 0.03,
     base: 0.045,
     loose: 0.06,
   } as const;
   
   /** Blur + fade + y-offset. Falls back to a plain fade under reduced motion. */
   export function enterVariants(reduceMotion?: boolean | null, y = 8): Variants {
     if (reduceMotion) {
       return {
         hidden: { opacity: 0 },
         visible: { opacity: 1, transition: { duration: duration.base } },
         exit: { opacity: 0, transition: { duration: duration.quick } },
       };
     }
     return {
       hidden: { opacity: 0, y, filter: "blur(4px)" },
       visible: {
         opacity: 1,
         y: 0,
         filter: "blur(0px)",
         transition: { duration: duration.base, ease: ease.out },
       },
       exit: {
         opacity: 0,
         y: -y / 2,
         filter: "blur(4px)",
         transition: { duration: duration.quick, ease: ease.out },
       },
     };
   }
   
   /** Scale 0.96 → 1 for popovers, menus and dialogs. */
   export function overlayVariants(reduceMotion?: boolean | null): Variants {
     if (reduceMotion) {
       return {
         hidden: { opacity: 0 },
         visible: { opacity: 1, transition: { duration: duration.quick } },
         exit: { opacity: 0, transition: { duration: duration.instant } },
       };
     }
     return {
       hidden: { opacity: 0, scale: 0.96, filter: "blur(2px)" },
       visible: {
         opacity: 1,
         scale: 1,
         filter: "blur(0px)",
         transition: { duration: duration.quick, ease: ease.out },
       },
       exit: {
         opacity: 0,
         scale: 0.96,
         filter: "blur(2px)",
         transition: { duration: duration.instant + 0.02, ease: ease.out },
       },
     };
   }
   
   /** Parent variants that stagger their children in. */
   export function staggerVariants(gap: number = stagger.base, delayChildren = 0): Variants {
     return {
       hidden: {},
       visible: { transition: { staggerChildren: gap, delayChildren } },
       exit: { transition: { staggerChildren: gap / 2, staggerDirection: -1 } },
     };
   }

   Show all 113 lines

3. Copy the source

   components/ui/progress-ring/progress-ring.tsx

   "use client";
   
   import { useEffect, useRef, type ComponentProps } from "react";
   import { animate, motion, useInView, useMotionValue, useReducedMotion, useTransform } from "motion/react";
   import { cn } from "@/lib/utils";
   import { ease } from "@/lib/motion";
   
   export interface ProgressRingProps
     extends Omit<ComponentProps<"div">, "children" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd"> {
     /** Current value. The ring and the label animate to it together. */
     value: number;
     /** Value at a full ring. @default 100 */
     max?: number;
     /** Accessible name, e.g. "Upload progress". */
     label: string;
     /** Diameter in px. @default 120 */
     size?: number;
     /** Ring thickness in px. @default 10 */
     thickness?: number;
     /** Fill color; the track is a light step of the same color. @default "var(--primary)" */
     color?: string;
     /** Text in the middle, given the animated value. @default a rounded percentage */
     formatValue?: (value: number, max: number) => string;
     /** Show the value in the middle. @default true */
     showValue?: boolean;
     /** Small caption under the value. */
     caption?: string;
   }
   
   const percentOf = (value: number, max: number) => `${Math.round((value / (max || 1)) * 100)}%`;
   
   export function ProgressRing({
     value,
     max = 100,
     label,
     size = 120,
     thickness = 10,
     color = "var(--primary)",
     formatValue = percentOf,
     showValue = true,
     caption,
     className,
     style,
     ...props
   }: ProgressRingProps) {
     const reduceMotion = useReducedMotion();
     const ref = useRef<HTMLDivElement>(null);
     const inView = useInView(ref, { once: true, amount: 0.5 });
     const target = Math.min(Math.max(value, 0), max);
     // One motion value drives both the stroke and the label, so they always agree.
     const progress = useMotionValue(0);
     const fraction = useTransform(progress, (v) => Math.min(1, Math.max(0, v / (max || 1))));
     const capOpacity = useTransform(fraction, (v) => (v > 0.001 ? 1 : 0));
     const text = useTransform(progress, (v) => formatValue(v, max));
   
     useEffect(() => {
       if (reduceMotion) {
         progress.set(target);
         return;
       }
       if (!inView) return;
       const controls = animate(progress, target, { duration: 1.1, ease: ease.out });
       return () => controls.stop();
     }, [target, inView, reduceMotion, progress]);
   
     const r = (size - thickness) / 2;
     const c = size / 2;
   
     return (
       <div
         ref={ref}
         role="progressbar"
         aria-label={label}
         aria-valuemin={0}
         aria-valuemax={max}
         aria-valuenow={target}
         aria-valuetext={formatValue(target, max)}
         className={cn("relative inline-flex shrink-0 items-center justify-center", className)}
         style={{ width: size, height: size, ...style }}
         {...props}
       >
         <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} className="absolute inset-0 -rotate-90" aria-hidden="true">
           <circle cx={c} cy={c} r={r} fill="none" stroke={`color-mix(in oklab, ${color} 14%, var(--background))`} strokeWidth={thickness} />
           <motion.circle
             cx={c}
             cy={c}
             r={r}
             fill="none"
             stroke={color}
             strokeWidth={thickness}
             strokeLinecap="round"
             style={{ pathLength: fraction, opacity: capOpacity }}
           />
         </svg>
         {showValue ? (
           <div aria-hidden="true" className="relative flex flex-col items-center leading-none">
             <motion.span className="font-semibold tracking-tight text-foreground" style={{ fontSize: Math.max(12, size * 0.2) }}>
               {text}
             </motion.span>
             {caption ? <span className="mt-1 text-xs text-muted-foreground">{caption}</span> : null}
           </div>
         ) : null}
       </div>
     );
   }

   Show all 105 lines

Usage#

import { ProgressRing } from "@/components/ui/progress-ring/progress-ring";

export function Upload({ percent }: { percent: number }) {
  return <ProgressRing value={percent} label="Upload progress" />;
}

// Custom range and label
<ProgressRing value={58} max={128} label="Photos storage" formatValue={(v) => `${Math.round(v)} GB`} />

API reference#

Accessibility#

• A real progressbar: aria-valuenow, aria-valuemax and a readable aria-valuetext (e.g. “58 GB”).
• The counting label is aria-hidden; screen readers get the final value from the progressbar.
• With reduced motion enabled, the ring and label jump straight to the value.