- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
"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
$ bunx --bun frakment add progress$ npx frakment add progress$ pnpm dlx frakment add progress$ yarn dlx frakment add progress
Copy and paste the following code into your project.
"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 };Update the import paths to match your project setup.
Usage
import { Progress } from "@/components/ui/progress";<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}%.
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
"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
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
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | Current progress. Values outside min..max are clamped. |
min | number | — | Minimum value. |
max | number | — | Maximum value. |
motion | string | — | CSS transition override for the indicator; e.g. 300 ease-out or 500 cubic-bezier(...). Respects prefers-reduced-motion. |
aria-label | string | — | Accessible name. Required when no visible label. |
children | React.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:
<Progress motion="300 cubic-bezier(0.34, 1.56, 0.64, 1)" value={60} />| Value | Result |
|---|---|
| omitted | 500ms 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.
const [value, setValue] = React.useState(50);
<Progress motion="off" value={value} />
<Slider onValueChange={(v) => setValue(v[0])} value={[value]} />Accessibility
- Renders
<div role="progressbar">witharia-valuenow,aria-valuemin, andaria-valuemaxmanaged automatically. - Pass
aria-labelwhen the progress is not self-describing (bar withoutProgressLabel). - Do not rely on color alone. Use
ProgressValueto show the numeric value.
Anatomy
<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
maxare clamped.