Progress Ring
A ring that fills on a spring toward a goal, with the percent rolling in the middle.
Preview
"use client";
import { useState } from "react";
import { useAutoplay } from "../demo-context";
import { ProgressRing } from "./ProgressRing";
const steps = [18, 46, 73, 100, 62];
export default function Demo() {
const [turn, setTurn] = useState(0);
useAutoplay(() => setTurn((t) => t + 1), 1600);
return <ProgressRing label="Monthly goal" value={steps[turn % steps.length]} />;
}Installation
npx @usefluid/cli add progress-ringpnpm dlx @usefluid/cli add progress-ringyarn dlx @usefluid/cli add progress-ringbunx @usefluid/cli add progress-ringInstall the engine.
Terminal npm i @usefluid/motionCopy these files into your project.
components/fluid/progress-ring/ProgressRing.tsx "use client"; import { useSpring } from "@usefluid/motion/react"; import { useMemo, useRef, useState } from "react"; import styles from "./ProgressRing.module.css"; const R = 52; const LENGTH = 2 * Math.PI * R; const FILL = { w: 8, z: 0.72 }; type Props = { label: string; value: number; max?: number; size?: number; locale?: string; color?: string; }; export function ProgressRing({ label, value, max = 100, size = 168, locale, color }: Props) { const arc = useRef<SVGCircleElement>(null); const out = useRef<HTMLSpanElement>(null); const percent = useMemo(() => new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 0 }), [locale]); const share = max > 0 ? Math.min(1, Math.max(0, value / max)) : 0; const [first] = useState(() => percent.format(share)); useSpring( { s: share }, ({ s }) => { const shown = Math.min(1.04, Math.max(0, s)); if (arc.current) arc.current.style.strokeDashoffset = `${LENGTH * (1 - shown)}`; if (out.current) out.current.textContent = percent.format(Math.min(1, Math.max(0, s))); }, FILL, ); return ( <div className={styles.root} role="progressbar" aria-label={label} aria-valuemin={0} aria-valuemax={max} aria-valuenow={Math.min(max, Math.max(0, value))} data-done={share >= 1 ? "" : undefined} style={{ width: size, ...(color ? { "--fluid-accent": color, "--fluid-on-accent": "#ffffff" } : {}) }} > <svg viewBox="0 0 120 120" className={styles.ring} aria-hidden> <circle cx={60} cy={60} r={R} className={styles.track} /> <circle ref={arc} cx={60} cy={60} r={R} className={styles.arc} strokeDasharray={LENGTH} strokeDashoffset={LENGTH * (1 - share)} /> </svg> <span className={styles.center} aria-hidden> <span ref={out} className={styles.value}> {first} </span> <span className={styles.label}>{label}</span> </span> </div> ); }components/fluid/progress-ring/ProgressRing.module.css .root { position: relative; display: grid; place-items: center; aspect-ratio: 1; color: var(--fluid-text); font-family: var(--fluid-font); } .ring { width: 100%; height: 100%; transform: rotate(-90deg); } .track, .arc { fill: none; stroke-width: 12; } .track { stroke: color-mix(in srgb, var(--fluid-text) 9%, transparent); } .arc { stroke: var(--fluid-accent); stroke-linecap: round; } .center { position: absolute; display: grid; justify-items: center; gap: 2px; max-width: 62%; text-align: center; } .value { font-size: 34px; font-weight: 600; font-variant-numeric: tabular-nums; letter-spacing: -0.03em; line-height: 1; } .label { color: var(--fluid-text-2); font-size: 12px; font-weight: 500; } .root[data-done] .arc { animation: done 600ms cubic-bezier(0.3, 1.6, 0.5, 1); } @keyframes done { 40% { stroke-width: 16; } } @media (prefers-reduced-motion: reduce) { .root[data-done] .arc { animation: none; } }Import the theme once, then point its variables at your own tokens.
layout.tsx import "@usefluid/motion/theme.css";
Usage
import { ProgressRing } from "./ProgressRing";
<ProgressRing label="Monthly goal" value={73} />API reference
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | What is measured. Shown under the percent and used as the accessible name. |
value | number | — | How much is done. Change it and the ring flows to it. |
max | number | 100 | The goal. |
size | number | 168 | Width and height in pixels. |
locale | string | the browser's | Locale for the percent. |
Keyboard and screen readers
A progress bar with its label, minimum, maximum and current value. With reduced motion the ring changes at once and does not swell.
Notes
The spring overshoots a little, so the ring passes its mark and comes back. Every colour comes from the --fluid-* variables, and the piece is yours to change.
How it is made
One spring drives both the arc and the number, with a little overshoot, so the ring passes its mark and settles back like something with weight. At the goal the stroke swells once. It is a progress bar for screen readers, with its label and values.
For your agent
For your agent
Add Progress Ring to my project with the Fluid library. Use ProgressRing for the goals and quotas of my dashboard, with the real targets. Read my project first. Use my logo, my colours and my font through the --fluid-* variables. Keep 44px touch targets, visible focus and reduced motion. If I have no SVG logo, ask before making one up.