Skip to content
Shaken UI
Sign in

Progress

Save

A 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
x
Preparing build environment
x
Set up your project

Connect repository

x
Storage usedx
Build cache restoredx
Indexing documentsx
Indexing

Installation

npx @shakenui/cli add progress

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add progress --dry-run

Usage

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

PropTypeDefaultDescription
valuenumber | null—Current value of Progress and ProgressRing. null makes them indeterminate. For ProgressSteps it is the number of finished steps.
min / maxnumber0 / 100Range of the value for Progress and ProgressRing.
labelReactNode—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.
showValueboolean—Shows the formatted value. On by default for a labeled bar with a value and for the lg ring.
valueTextReactNode—Replaces the visible value on Progress, such as "48 of 120 MB". Pair it with getAriaValueText.
format / getAriaValueTextIntl.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 / stepsnumber / 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.tsxShow
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>
  );
}