When to use
- A task with a known length: an upload, an export, a migration, steps of an import.
- A task that starts with an unknown length and learns it later: pass
nulluntil the first value arrives. - A quota or usage meter that fills towards a limit, such as storage used.
When not to use
Installation
pnpm dlx shadcn add https://eased.dev/r/progress.jsonnpx shadcn add https://eased.dev/r/progress.jsonyarn dlx shadcn add https://eased.dev/r/progress.jsonbunx --bun shadcn add https://eased.dev/r/progress.jsonThe command adds Progress, everything it builds on and Eased’s tokens to your project.
Install the dependencies
pnpm add motion @base-ui/reactnpm install motion @base-ui/reactyarn add motion @base-ui/reactbun add motion @base-ui/reactAdd the Eased pieces it builds on
Copy each item’s files the same way, or install them with the CLI:
Copy the source into your project
components/eased/progress/progress.tsxTSX "use client";import { Progress as BaseProgress } from "@base-ui/react/progress";import { AnimatePresence, motion, useInView } from "motion/react";import { useRef, useState, type ReactNode } from "react";import { NumberRoll } from "../_primitives/number-roll/number-roll";import { enter, exit, instant, reducedFade, smooth, useSafeReducedMotion } from "../lib/motion";export type ProgressProps = { /** Current value, from `min` to `max`. `null` is indeterminate: the length of the task is unknown. */ value: number | null; min?: number; max?: number; /** Visible label, also the progressbar's accessible name. Without one, pass `aria-label`. */ label?: ReactNode; "aria-label"?: string; /** Show the rolling value on the right of the label row. Default true; hidden while indeterminate. */ showValue?: boolean; /** Formats the value, e.g. `{ style: "unit", unit: "megabyte" }`. Default: the percentage. */ format?: Intl.NumberFormatOptions; locale?: Intl.LocalesArgument; /** Spoken value, e.g. `(formatted) => \`${formatted} uploaded\``. */ getAriaValueText?: (formattedValue: string, value: number | null) => string; /** Track thickness: 4px (`sm`) or 6px (`md`). Default `md`. */ size?: "sm" | "md"; /** Turn the bar success-green when it reaches `max`. Default true. */ successOnComplete?: boolean; className?: string;};const TRACK = { sm: "h-1", md: "h-1.5" } as const;/** * A progress bar on Base UI's Progress. The determinate bar rides a spring (no overshoot, so it * never reads past the real value) and its value rolls; an unknown length sweeps with an * accelerate–decelerate curve, then hands over to the bar the moment a value arrives. */export function Progress({ value, min = 0, max = 100, label, "aria-label": ariaLabel, showValue = true, format, locale, getAriaValueText, size = "md", successOnComplete = true, className = "",}: ProgressProps) { const reduced = useSafeReducedMotion(); const track = useRef<HTMLDivElement>(null); const inView = useInView(track); const known = value != null && Number.isFinite(value); const clamped = known ? Math.min(max, Math.max(min, value)) : min; const fraction = max > min ? (clamped - min) / (max - min) : 0; const complete = known && clamped === max; // While indeterminate the hidden bar holds its last value, so it neither rewinds as it fades // out nor refills from empty when a value returns. const [held, setHeld] = useState(fraction); if (known && fraction !== held) setHeld(fraction); return ( <BaseProgress.Root value={value} min={min} max={max} format={format} locale={locale} getAriaValueText={getAriaValueText} aria-label={label ? undefined : ariaLabel} className={`flex w-full min-w-0 flex-col gap-2 ${className}`} > {(label || (showValue && known)) && ( <div className="flex min-w-0 items-baseline justify-between gap-3 text-ui-sm"> {label ? <BaseProgress.Label className="min-w-0 truncate text-text-secondary">{label}</BaseProgress.Label> : <span />} {showValue && ( <span className="shrink-0 text-text-muted tabular-nums"> <AnimatePresence initial={false}> {known && ( <motion.span className="inline-block" initial={{ opacity: 0 }} animate={{ opacity: 1, transition: reduced ? reducedFade : enter }} exit={{ opacity: 0, transition: reduced ? reducedFade : exit }} > <NumberRoll aria-hidden value={format ? clamped : fraction} locale={locale} format={format ?? { style: "percent", maximumFractionDigits: 0 }} /> </motion.span> )} </AnimatePresence> </span> )} </div> )} <BaseProgress.Track ref={track} className={`relative w-full overflow-clip rounded-pill bg-surface-sunken inset-shadow-well ${TRACK[size]}`} > {/* Determinate: a full-width bar slid in from the left, so its rounded end never squashes. */} <motion.div className={`absolute inset-0 rounded-pill transition-colors duration-150 ease-standard ${ complete && successOnComplete ? "bg-success" : "bg-brand" }`} initial={false} animate={{ x: `${(held - 1) * 100}%`, opacity: known ? 1 : 0 }} transition={reduced ? instant : { ...smooth, opacity: known ? enter : exit }} /> {/* Indeterminate: a 40% segment that accelerates in and decelerates out, then repeats. */} <AnimatePresence initial={false}> {!known && ( <motion.div key="sweep" className="absolute inset-y-0 left-0 w-2/5 animate-[eased-progress-sweep_1600ms_var(--eased-ease-in-out)_infinite] rounded-pill bg-brand reduced:w-full reduced:animate-none" style={{ animationPlayState: inView ? "running" : "paused" }} initial={{ opacity: 0 }} animate={{ opacity: reduced ? 0.4 : 1, transition: reduced ? reducedFade : enter }} exit={{ opacity: 0, transition: reduced ? reducedFade : exit }} /> )} </AnimatePresence> <style href="eased-progress" precedence="default"> {"@keyframes eased-progress-sweep { from { translate: -100% 0; } to { translate: 250% 0; } }"} </style> </BaseProgress.Track> </BaseProgress.Root> );}Keep the folder layout
The files import each other by relative path (
../lib/motion), so keep each one at the path shown, undercomponents/eased/.
Usage
import { Progress } from "@/components/eased/progress/progress";export function UploadProgress({ sent }: { sent: number | null }) { return <Progress label="Launch film final.mov" value={sent} max={842} />;}Examples
Indeterminate
null sweeps a segment across the track until the length is known; the value is hidden meanwhile.
<Progress label="Processing" value={null} />Units instead of a percentage
format shows and speaks the value itself rather than a percentage.
<Progress label="Storage" value={7.4} max={10} format={{ style: "unit", unit: "gigabyte", maximumFractionDigits: 1 }} successOnComplete={false} size="sm"/>API reference
Progress
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | null | Current value. null is indeterminate. | |
min / max | number | 0 / 100 | |
label | ReactNode | Visible label and the accessible name. | |
aria-label | string | The accessible name when there is no label. | |
showValue | boolean | true | The rolling value on the right of the label row; hidden while indeterminate. |
format | Intl.NumberFormatOptions | whole-number percent | Formats the shown and spoken value. |
locale | Intl.LocalesArgument | ||
getAriaValueText | (formattedValue: string, value: number | null) => string | The spoken value, e.g. (f) => `${f} uploaded`. | |
size | "sm" | "md" | "md" | 4px or 6px track. |
successOnComplete | boolean | true | The bar turns success green at max. |
className | string | "" | Appended to the root's classes. |
Values outside min and max are clamped for the bar and the shown value.
Accessibility
- Base UI renders
role="progressbar"witharia-valuenow,aria-valuemin,aria-valuemaxandaria-valuetext; while indeterminate there is noaria-valuenow. - The label names the bar; without a visible label, pass
aria-label. - The visible rolling value is hidden from assistive tech, so the value is read once, from the progressbar.
Motion
The bar rides the smooth spring, which never overshoots, so it never reads past the real value. It is a full-width bar sliding in from the left rather than a growing width, so its rounded end never squashes. The value rolls its digits. An unknown length sweeps a 40% segment across the track every 1.6s on an accelerate–decelerate curve, paused while off-screen, and fades out as the bar fades in the moment a value arrives. Completing turns the bar green over 150ms. Reduced motion: the bar jumps to each value and the sweep becomes a still, faint full-width tint.
Notes for AI
Use Progress whenever there is a number to show, and pass null (not 0) while the length is unknown so it sweeps instead of sitting empty. Give it a label that names the task, and format when the units mean more than a percentage; turn off successOnComplete for meters where full is not success.
Do not animate the value yourself or throttle updates for smoothness: the spring smooths jumps, and the value rolls. Do not swap between a spinner and a bar when the length becomes known; the indeterminate state already hands over.
Related components
- Loading Spinner: a wait with nothing to measure.
- Animated Number Counter: the rolling value on its own.
- Skeleton Loader: placeholders for loading content.