For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Progress

Displays an indicator showing the completion progress of a task.

Web
Frakment
progress.tsx
"use client";

import * as React from "react";

import {
  getTransition,
  parseMotion,
  useMotionGuard,
  useReducedMotion,
} from "@/lib/motion";
import { cn } from "@/lib/utils";

const ProgressContext = React.createContext<{ value?: number }>({});

type ProgressProps = Omit<React.ComponentProps<"div">, "role"> & {
  "aria-label"?: string;
  children?: React.ReactNode;
  max?: number;
  min?: number;
  motion?: string;
  value?: number;
};

function useProgressIndicatorStyle(
  value: number,
  min: number,
  max: number,
  motion: string | undefined,
  internalRef: React.RefObject<HTMLDivElement | null>
): React.CSSProperties {
  const reduce = useReducedMotion();
  const clamped = Math.min(Math.max(value, min), max);
  const range = Math.max(max - min, 1);
  const percent = ((clamped - min) / range) * 100;

  let style: React.CSSProperties = {
    transform: `translateX(-${100 - percent}%)`,
  };

  if (reduce) {
    style.transition = "none";
  } else if (motion !== undefined) {
    const transition = getTransition(parseMotion(motion));
    if (transition) {
      style.transition = transition;
    }
  }

  const motionEnabled = motion !== undefined && !reduce;
  const fingerprint = JSON.stringify(style);
  const yielded = useMotionGuard(internalRef, motionEnabled, fingerprint);
  if (yielded && !reduce) {
    style = { ...style, transition: "none" };
  }

  return style;
}

function ProgressBar({
  className,
  max = 100,
  min = 0,
  motion,
  value,
  ...props
}: ProgressProps) {
  const internalRef = React.useRef<HTMLDivElement | null>(null);
  const safeValue = value ?? 0;
  const indicatorStyle = useProgressIndicatorStyle(
    safeValue,
    min,
    max,
    motion,
    internalRef
  );

  return (
    <div
      aria-valuemax={max}
      aria-valuemin={min}
      aria-valuenow={safeValue}
      className={cn(
        "bg-primary/20 relative flex h-1 w-full items-center overflow-x-hidden rounded-full",
        className
      )}
      data-slot="progress"
      role="progressbar"
      {...props}
    >
      <div
        className={cn(
          "bg-primary size-full flex-1",
          motion === undefined && "transition-transform duration-500 ease-out"
        )}
        data-slot="progress-indicator"
        ref={internalRef}
        style={indicatorStyle}
      />
    </div>
  );
}

function Progress({ className, value, children, ...props }: ProgressProps) {
  const normalizedValue = value ?? 0;

  if (!children) {
    return (
      <ProgressBar className={className} value={normalizedValue} {...props} />
    );
  }

  return (
    <ProgressContext.Provider value={{ value: normalizedValue }}>
      <div className={cn("flex flex-col gap-2", className)}>
        <div className="flex items-center justify-between gap-2">
          {children}
        </div>
        <ProgressBar value={normalizedValue} {...props} />
      </div>
    </ProgressContext.Provider>
  );
}

function ProgressLabel({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      className={cn("text-sm font-medium", className)}
      data-slot="progress-label"
      {...props}
    />
  );
}

function ProgressValue({ className, ...props }: React.ComponentProps<"span">) {
  const { value } = React.useContext(ProgressContext);
  return (
    <span
      className={cn("text-muted-foreground text-sm tabular-nums", className)}
      data-slot="progress-value"
      {...props}
    >
      {value ?? 0}%
    </span>
  );
}

export { Progress, ProgressLabel, ProgressValue };

Progress shows how much of a task has completed. The indicator animates smoothly on every value change with a 500ms ease-out transform by default. Override with the motion prop.

Installation

Usage

progress.tsx
import { Progress } from "@/components/ui/progress";
tsx
<Progress value={60} />

Examples

With label and value

Pass ProgressLabel and ProgressValue as children to render a header row above the bar. ProgressValue reads the current value from context and renders {value}%.

Upload progress56%
progress-with-label.tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress";

export function ProgressWithLabel() {
  return (
    <Progress className="w-full max-w-sm" value={56}>
      <ProgressLabel>Upload progress</ProgressLabel>
      <ProgressValue />
    </Progress>
  );
}

Controlled

progress-controlled.tsx
"use client";

import * as React from "react";

import { Progress } from "@/components/ui/progress";
import { Slider } from "@/components/ui/slider";

export function ProgressControlled() {
  const [value, setValue] = React.useState(50);

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <Progress className="w-full" motion="off" value={value} />
      <Slider
        aria-label="Progress value"
        className="w-full"
        max={100}
        min={0}
        onValueChange={(value) => setValue(value[0])}
        step={1}
        value={[value]}
      />
    </div>
  );
}

In Context

File upload list

design-system.zip82%
annual-report.pdf34%
progress-file-upload-list.tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress";

export function ProgressFileUploadList() {
  return (
    <div className="mx-auto w-full max-w-sm space-y-4">
      <Progress value={82}>
        <ProgressLabel>design-system.zip</ProgressLabel>
        <ProgressValue />
      </Progress>
      <Progress value={34}>
        <ProgressLabel>annual-report.pdf</ProgressLabel>
        <ProgressValue />
      </Progress>
    </div>
  );
}

API Reference

Progress

PropTypeDefaultDescription
valuenumber—Current progress. Values outside min..max are clamped.
minnumber—Minimum value.
maxnumber—Maximum value.
motionstring—CSS transition override for the indicator; e.g. 300 ease-out or 500 cubic-bezier(...). Respects prefers-reduced-motion.
aria-labelstring—Accessible name. Required when no visible label.
childrenReact.ReactNode—Optional label and value row rendered above the bar.

ProgressLabel

Extends React.ComponentProps<"span">. Renders the label on the left of the header row.

ProgressValue

Extends React.ComponentProps<"span">. Reads value from ProgressContext and renders {value}%.

Motion

The indicator uses a CSS transition-transform (500ms ease-out) by default. Override with motion:

tsx
<Progress motion="300 cubic-bezier(0.34, 1.56, 0.64, 1)" value={60} />
ValueResult
omitted500ms ease-out
"200"200ms ease-in-out
"500 cubic-bezier(...)"500ms custom easing
"off"instant (no transition)

When prefers-reduced-motion is set, the transition is disabled regardless of the value. Third-party animation libraries that write inline styles to the indicator automatically suppress the internal CSS transition.

Live updates (slider, input)

When the value changes rapidly — drag slider, typing, real-time upload — pass motion="off" so the fill updates instantly instead of trailing 500ms behind.

tsx
const [value, setValue] = React.useState(50);
 
<Progress motion="off" value={value} />
<Slider onValueChange={(v) => setValue(v[0])} value={[value]} />

Accessibility

  • Renders <div role="progressbar"> with aria-valuenow, aria-valuemin, and aria-valuemax managed automatically.
  • Pass aria-label when the progress is not self-describing (bar without ProgressLabel).
  • Do not rely on color alone. Use ProgressValue to show the numeric value.

Anatomy

tsx
<Progress value={60}>
  <ProgressLabel />
  <ProgressValue />
</Progress>
  • Root — track background
  • Indicator — filled portion driven by value
  • Label — left-aligned heading, optional
  • Value — right-aligned percentage

Best Practices

  • Always show the value. A bar alone is ambiguous.
  • Use determinate for known tasks. Spinners for unknown.
  • Keep animation under 1s. 500ms ease-out default.
  • Cap at 100. Values above max are clamped.