Progress
SaveA progress bar with label and value, an indeterminate band, a segmented steps bar, and a circular ring, all on Base UI Progress.
- Category
- Feedback
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Progress preview
Uploading site-assets.zip18 of 120 MB
Preparing build environment
Set up your project
Connect repository
Storage used
Build cache restored
Indexing documents
IndexingInstallation
npx @shakenui/cli add progressReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add progress --dry-runUsage
progress-example.tsx
"use client";
import { useEffect, useState } from "react";
import { Button } from "@/components/shaken/ui/button";
import { Progress, ProgressRing, ProgressSteps } from "@/components/shaken/ui/progress";
const steps = ["Create workspace", "Connect repository", "Add a domain", "Invite your team"];
export default function ProgressExample() {
const [uploaded, setUploaded] = useState(18);
const [step, setStep] = useState(1);
// Upload a 120 MB archive in uneven chunks, the way a real upload reports progress.
useEffect(() => {
if (uploaded >= 120) return;
const timer = setTimeout(() => setUploaded((mb) => Math.min(120, mb + 6 + Math.round(Math.random() * 14))), 700);
return () => clearTimeout(timer);
}, [uploaded]);
const done = uploaded >= 120;
return (
<div className="grid w-full max-w-md gap-8">
<div className="grid gap-3">
<Progress
label="Uploading site-assets.zip"
value={uploaded}
max={120}
tone={done ? "success" : "neutral"}
valueText={done ? "Uploaded" : `${uploaded} of 120 MB`}
getAriaValueText={(_, mb) => `${mb} of 120 megabytes`}
/>
<Button size="sm" variant="secondary" className="justify-self-start" onClick={() => setUploaded(0)} disabled={!done}>
Upload again
</Button>
</div>
<Progress label="Preparing build environment" value={null} tone="info" size="sm" />
<div className="grid gap-3">
<ProgressSteps label="Set up your project" total={steps.length} value={step} steps={steps} />
<div className="flex gap-2">
<Button size="sm" variant="secondary" onClick={() => setStep((s) => Math.max(0, s - 1))} disabled={step === 0}>
Back
</Button>
<Button size="sm" onClick={() => setStep((s) => Math.min(steps.length, s + 1))} disabled={step === steps.length}>
{step === steps.length - 1 ? "Finish" : "Next step"}
</Button>
</div>
</div>
<div className="flex items-center gap-6">
<ProgressRing label="Storage used" value={72} size="lg" tone="warning" />
<ProgressRing label="Build cache restored" value={40} />
<div className="flex items-center gap-2 text-sm text-zinc-600 dark:text-zinc-400">
<ProgressRing label="Indexing documents" value={null} size="sm" tone="info" />
Indexing
</div>
</div>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | null | — | Current value of Progress and ProgressRing. null makes them indeterminate. For ProgressSteps it is the number of finished steps. |
| min / max | number | 0 / 100 | Range of the value for Progress and ProgressRing. |
| label | ReactNode | — | Names the progressbar. Visible above the bar and the steps; visually hidden on the ring. Without it, pass aria-label. |
| tone | "neutral" | "info" | "success" | "warning" | "danger" | "neutral" | Fill hue. Neutral is monochrome; info suits running work, the others outcomes. |
| showValue | boolean | — | Shows the formatted value. On by default for a labeled bar with a value and for the lg ring. |
| valueText | ReactNode | — | Replaces the visible value on Progress, such as "48 of 120 MB". Pair it with getAriaValueText. |
| format / getAriaValueText | Intl.NumberFormatOptions / (formatted, value) => string | — | Formats the value text and the spoken aria-valuetext. |
| size | "sm" | "md" (Progress) | "sm" | "md" | "lg" (ProgressRing) | "md" | Bar height 4 or 6px; ring diameter 20, 40, or 64px. |
| ProgressSteps total / steps | number / string[] | — | Number of segments, and optional step names; the current step's name is shown and spoken with the count. |
Accessibility
- Every variant renders role="progressbar" through Base UI Progress with aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext; the label is linked with aria-labelledby.
- Indeterminate bars and rings omit aria-valuenow, so screen readers announce indeterminate progress.
- ProgressSteps speaks the position and the step name, for example "Step 2 of 4: Connect repository".
- The fill moves with transform (translate and scale) only; the ring animates stroke-dashoffset. All value transitions are removed under reduced motion.
- Under reduced motion the indeterminate band is replaced by a still dotted fill and the indeterminate ring holds a still arc.
- Color is never the only signal: the value text, step count, or label carries the state.
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/progress.tsxprogress- Also installs button@0.2.1registry dependency
- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/progress/0.1.0.json.
ui/progress.tsxShowHide
ui/progress.tsx
"use client";
import { Progress as BaseProgress } from "@base-ui/react/progress";
import { type ReactNode, useEffect, useRef } from "react";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
/*
* Progress on Base UI Progress (role="progressbar", aria-valuenow/min/max/valuetext, and the
* label wired through aria-labelledby). The fill moves with transform only: the bar is full
* width and slides in from the left, so value changes never trigger layout.
*/
export type ProgressTone = "neutral" | "info" | "success" | "warning" | "danger";
// The fill is drawn in currentColor, so one class sets the hue for bar, segments, and ring.
const tones: Record<ProgressTone, string> = {
neutral: "text-zinc-950 dark:text-white",
info: "text-sky-500 dark:text-sky-400",
success: "text-emerald-500 dark:text-emerald-400",
warning: "text-amber-500 dark:text-amber-400",
danger: "text-red-500 dark:text-red-400",
};
const track = "bg-zinc-950/[0.07] dark:bg-white/[0.1]";
const fillMotion = "transition-[translate,scale,opacity] duration-500 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none";
function percentOf(value: number, min: number, max: number) {
if (max <= min) return 0;
return Math.min(100, Math.max(0, ((value - min) / (max - min)) * 100));
}
/** Slides an indeterminate band across its track. Shared start time keeps several bars in step. */
function useIndeterminate(active: boolean) {
const ref = useRef<HTMLSpanElement>(null);
useEffect(() => {
const band = ref.current;
if (!active || !band || typeof band.animate !== "function") return;
const motion = window.matchMedia("(prefers-reduced-motion: reduce)");
let animation: Animation | undefined;
const start = () => {
animation?.cancel();
animation = undefined;
if (motion.matches) return;
animation = band.animate(
[{ transform: "translateX(-100%)" }, { transform: "translateX(250%)" }],
{ duration: 1600, iterations: Infinity, easing: "cubic-bezier(0.65, 0, 0.35, 1)" },
);
animation.startTime = 0;
};
start();
motion.addEventListener("change", start);
return () => {
animation?.cancel();
motion.removeEventListener("change", start);
};
}, [active]);
return ref;
}
interface SharedProps {
/** Current value. `null` makes it indeterminate (work is happening, amount unknown). */
value: number | null;
min?: number;
max?: number;
/** Visible label above the bar; it also names the progressbar. Without it, pass `aria-label`. */
label?: ReactNode;
/** Fill hue. Neutral is monochrome; use info for running work and the other tones for outcomes. */
tone?: ProgressTone;
/** Formats the value text and `aria-valuetext`, for example `{ style: "unit", unit: "megabyte" }`. */
format?: Intl.NumberFormatOptions;
/** Custom spoken value, e.g. `(formatted, value) => \`${value} of 12 files\``. */
getAriaValueText?: (formattedValue: string, value: number | null) => string;
className?: string;
"aria-label"?: string;
"aria-labelledby"?: string;
}
export interface ProgressProps extends SharedProps {
/** Shows the formatted value at the end of the label row. Defaults to on when there is a label and a value. */
showValue?: boolean;
/** Replaces the value text, e.g. "48 of 120 MB". */
valueText?: ReactNode;
/** Track height: 4px or 6px. */
size?: "sm" | "md";
}
/** A determinate or indeterminate progress bar with an optional label and value. */
export function Progress({
value,
min = 0,
max = 100,
label,
tone = "neutral",
showValue,
valueText,
size = "md",
className,
...props
}: ProgressProps) {
const indeterminate = value === null;
const band = useIndeterminate(indeterminate);
const pct = indeterminate ? 0 : percentOf(value, min, max);
const valueVisible = showValue ?? (label != null && !indeterminate);
return (
<BaseProgress.Root value={value} min={min} max={max} className={cx("grid w-full gap-2", className)} {...props}>
{label != null || valueVisible ? (
<div className="flex items-baseline justify-between gap-4 text-sm leading-5">
{label != null ? (
<BaseProgress.Label className="min-w-0 truncate font-medium text-zinc-950 dark:text-white">{label}</BaseProgress.Label>
) : (
<span />
)}
{valueVisible ? (
valueText != null ? (
<span className="shrink-0 font-mono text-xs text-zinc-500 tabular-nums">{valueText}</span>
) : (
<BaseProgress.Value className="shrink-0 font-mono text-xs text-zinc-500 tabular-nums" />
)
) : null}
</div>
) : null}
<BaseProgress.Track
className={cx("relative w-full overflow-hidden rounded-full", size === "sm" ? "h-1" : "h-1.5", track, tones[tone])}
>
{indeterminate ? (
<>
<span
ref={band}
style={{ transform: "translateX(-100%)" }}
className="absolute inset-y-0 left-0 w-2/5 rounded-full bg-current motion-reduce:hidden"
/>
{/* Reduced motion: a still dotted fill says "in progress, amount unknown" without moving. */}
<span className="absolute inset-0 hidden bg-[radial-gradient(circle,currentColor_1px,transparent_1.5px)] bg-size-[6px_100%] bg-repeat-x opacity-50 motion-reduce:block" />
</>
) : (
<span
data-slot="progress-fill"
className={cx("absolute inset-0 rounded-full bg-current", fillMotion)}
style={{ translate: `${pct - 100}% 0` }}
/>
)}
</BaseProgress.Track>
</BaseProgress.Root>
);
}
export interface ProgressStepsProps extends Omit<SharedProps, "value" | "min" | "max" | "format"> {
/** Number of steps. */
total: number;
/** Steps finished so far (0 to total). The next one is drawn as the current step. */
value: number;
/** Name of each step. The current step's name is shown and spoken with the count. */
steps?: string[];
}
/** A segmented bar for multi-step flows: finished segments are filled, the current one is tinted. */
export function ProgressSteps({ total, value, steps, label, tone = "neutral", className, getAriaValueText, ...props }: ProgressStepsProps) {
const done = Math.min(total, Math.max(0, Math.round(value)));
const complete = done >= total;
const currentIndex = Math.min(done, total - 1);
const currentName = steps?.[currentIndex];
const position = complete ? `All ${total} steps complete` : `Step ${done + 1} of ${total}`;
const spoken = currentName && !complete ? `${position}: ${currentName}` : position;
return (
<BaseProgress.Root
value={done}
min={0}
max={total}
getAriaValueText={getAriaValueText ?? (() => spoken)}
className={cx("grid w-full gap-2", className)}
{...props}
>
<div className="flex items-baseline justify-between gap-4 text-sm leading-5">
{label != null ? (
<BaseProgress.Label className="min-w-0 truncate font-medium text-zinc-950 dark:text-white">{label}</BaseProgress.Label>
) : currentName && !complete ? (
<span className="min-w-0 truncate font-medium text-zinc-950 dark:text-white">{currentName}</span>
) : (
<span />
)}
<span aria-hidden="true" className="shrink-0 text-xs text-zinc-500 tabular-nums">
{complete ? "Done" : `Step ${done + 1} of ${total}`}
</span>
</div>
<div aria-hidden="true" className={cx("flex gap-1", tones[tone])}>
{Array.from({ length: total }, (_, i) => {
const state = i < done ? "complete" : i === done ? "current" : "pending";
return (
<span key={i} data-state={state} className={cx("relative h-1.5 flex-1 overflow-hidden rounded-full", track)}>
<span
className={cx(
"absolute inset-0 origin-left rounded-full bg-current",
fillMotion,
state === "complete" ? "scale-x-100 opacity-100" : state === "current" ? "scale-x-100 opacity-30" : "scale-x-0 opacity-0",
)}
/>
</span>
);
})}
</div>
{label != null && currentName && !complete ? <p className="text-xs leading-4 text-zinc-500">{currentName}</p> : null}
</BaseProgress.Root>
);
}
const ringSizes = { sm: { px: 20, stroke: 2.25 }, md: { px: 40, stroke: 3 }, lg: { px: 64, stroke: 4 } } as const;
export interface ProgressRingProps extends SharedProps {
/** 20px (inline, no value), 40px, or 64px. */
size?: keyof typeof ringSizes;
/** Shows the value in the center (md and lg). Defaults to on for lg. */
showValue?: boolean;
/** Replaces the centered content, e.g. an icon or "3/8". */
children?: ReactNode;
}
/**
* A circular progress ring. The label is visually hidden (the ring has no room for it) but
* names the progressbar; place visible text beside the ring when you need it.
*/
export function ProgressRing({
value,
min = 0,
max = 100,
label,
tone = "neutral",
size = "md",
showValue,
children,
className,
...props
}: ProgressRingProps) {
const indeterminate = value === null;
const { px, stroke } = ringSizes[size];
const r = (px - stroke) / 2;
const circumference = 2 * Math.PI * r;
const pct = indeterminate ? 25 : percentOf(value, min, max);
const valueVisible = (showValue ?? size === "lg") && size !== "sm" && !indeterminate;
return (
<BaseProgress.Root
value={value}
min={min}
max={max}
className={cx("relative inline-flex shrink-0 items-center justify-center", tones[tone], className)}
style={{ width: px, height: px }}
{...props}
>
{label != null ? <BaseProgress.Label className="sr-only">{label}</BaseProgress.Label> : null}
<svg
aria-hidden="true"
width={px}
height={px}
viewBox={`0 0 ${px} ${px}`}
fill="none"
className={cx("-rotate-90", indeterminate && "motion-safe:animate-spin motion-safe:[animation-duration:1.2s]")}
>
<circle cx={px / 2} cy={px / 2} r={r} stroke="currentColor" strokeWidth={stroke} className="opacity-[0.12] dark:opacity-[0.16]" />
<circle
cx={px / 2}
cy={px / 2}
r={r}
stroke="currentColor"
strokeWidth={stroke}
strokeLinecap="round"
strokeDasharray={circumference}
strokeDashoffset={circumference * (1 - pct / 100)}
className={cx(
"transition-[stroke-dashoffset] duration-500 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none",
!indeterminate && pct === 0 && "opacity-0",
)}
/>
</svg>
{children != null ? (
<span className="absolute inset-0 flex items-center justify-center text-zinc-950 dark:text-white">{children}</span>
) : valueVisible ? (
<BaseProgress.Value
className={cx(
"absolute inset-0 flex items-center justify-center font-mono font-medium text-zinc-950 tabular-nums dark:text-white",
size === "lg" ? "text-sm" : "text-[10px]",
)}
/>
) : null}
</BaseProgress.Root>
);
}