A Radix progress bar with clamped values, optional percentage text, and a reduced-motion-safe pending state.
Organizing 48 documents into your workspace
import { Progress } from "@/components/ballmac/progress"
export default function ProgressDemo() {
return (
<div className="w-full max-w-sm rounded-xl border bg-card p-5 shadow-sm">
<div className="flex justify-between gap-3 text-sm">
<span className="font-semibold">Importing your files</span>
<span className="text-muted-foreground">Step 3 of 4</span>
</div>
<p className="mt-1 mb-5 text-xs text-muted-foreground">
Organizing 48 documents into your workspace
</p>
<Progress value={68} showValue aria-label="Import progress" />
</div>
)
}Installation
The default, and what a Radix-style project installs.
$ pnpm dlx shadcn@latest add @ballmac/progressInstall the dependencies.
$ pnpm add radix-uiCopy the source into your project.
components/ballmac/progress.tsx// Ballmac UI: Progress. https://ui.ballmac.com/components/progress // Based on shadcn/ui Progress (MIT, Copyright (c) 2023 shadcn), adding a labeled value and reduced-motion-safe indeterminate state. import * as React from "react" import { Progress as ProgressPrimitive } from "radix-ui" import { cn } from "@/lib/utils" type ProgressProps = React.ComponentProps<typeof ProgressPrimitive.Root> & { /** Show the value in a label below the bar. */ showValue?: boolean } function Progress({ className, value, max = 100, showValue = false, ...props }: ProgressProps) { const safeMax = Number.isFinite(max) && max > 0 ? max : 100 const safeValue = value == null ? null : Math.max(0, Math.min(safeMax, value)) const percent = safeValue == null ? null : Math.round((safeValue / safeMax) * 100) return ( <div data-slot="progress-group" className={cn("w-full", className)}> <ProgressPrimitive.Root data-slot="progress" value={safeValue} max={safeMax} className="bg-muted relative h-2 w-full overflow-hidden rounded-full" {...props} > <ProgressPrimitive.Indicator data-slot="progress-indicator" className={cn( "bg-primary block h-full rounded-full transition-[width] duration-200 motion-reduce:transition-none", percent == null && "w-1/3 motion-safe:animate-pulse motion-reduce:w-full", )} style={percent == null ? undefined : { width: `${percent}%` }} /> </ProgressPrimitive.Root> {showValue && ( <span data-slot="progress-value" className="text-muted-foreground mt-2 block text-end text-xs tabular-nums" > {percent == null ? "In progress" : `${percent}%`} </span> )} </div> ) } export { Progress, type ProgressProps }Update the import paths to match your project setup.
$ pnpm dlx shadcn@latest add https://ui.ballmac.com/r/base/progress.jsonInstall the dependencies.
$ pnpm add @base-ui/react@^1.9.0Copy the source into your project.
components/ballmac/progress.tsx// Ballmac UI: Progress. https://ui.ballmac.com/components/progress // Based on shadcn/ui Progress (MIT, Copyright (c) 2023 shadcn), adding a labeled value and reduced-motion-safe indeterminate state. import * as React from "react" import { Progress as ProgressPrimitive } from "@base-ui/react/progress" import { cn } from "@/lib/utils" type ProgressProps = Omit<React.ComponentProps<typeof ProgressPrimitive.Root>, "value" | "className"> & { className?: string /** The current value. Leave it out (or pass null) for an indeterminate bar. */ value?: number | null /** Show the value in a label below the bar. */ showValue?: boolean } function Progress({ className, value, max = 100, showValue = false, ...props }: ProgressProps) { const safeMax = Number.isFinite(max) && max > 0 ? max : 100 const safeValue = value == null ? null : Math.max(0, Math.min(safeMax, value)) const percent = safeValue == null ? null : Math.round((safeValue / safeMax) * 100) return ( <div data-slot="progress-group" className={cn("w-full", className)}> <ProgressPrimitive.Root data-slot="progress" value={safeValue} max={safeMax} className="bg-muted relative h-2 w-full overflow-hidden rounded-full" {...props} > <ProgressPrimitive.Indicator data-slot="progress-indicator" className={cn( "bg-primary block h-full rounded-full transition-[width] duration-200 motion-reduce:transition-none", percent == null && "w-1/3 motion-safe:animate-pulse motion-reduce:w-full", )} style={percent == null ? undefined : { width: `${percent}%` }} /> </ProgressPrimitive.Root> {showValue && ( <span data-slot="progress-value" className="text-muted-foreground mt-2 block text-end text-xs tabular-nums" > {percent == null ? "In progress" : `${percent}%`} </span> )} </div> ) } export { Progress, type ProgressProps }Update the import paths to match your project setup.
Usage
import { Progress } from "@/components/ballmac/progress"The full example is in the Code tab above.
Examples
States and variants
import { Progress } from "@/components/ballmac/progress"
export default function ProgressStates() {
return (
<div className="flex w-full max-w-sm flex-col gap-4">
<div className="text-sm font-medium">Almost there</div>
<Progress value={91} showValue aria-label="Upload progress" />
<div className="text-sm font-medium">Waiting for a response</div>
<Progress value={null} showValue aria-label="Connection progress" />
</div>
)
}API reference
| Prop | Type | Default |
|---|---|---|
showValueShow the value in a label below the bar. | boolean | false |
Also accepts the standard attributes of its root element.
Quality scorecard
Every applicable check passes
Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.
Passed: Accessibility scan
No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).
Passed: Small screens
No sideways scrolling at 360, 390 or 1280 px wide.
Passed: Reduced motion
Every endless animation stops when the visitor asks for less motion.
Passed: Right to left
Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).
Passed: Clean console
No console errors or React hydration errors while loading.
Not applicable: Keyboard
Static content: nothing to focus.
Not applicable: Loading, empty and error
Does not show data or take submissions.
For information: Automated tests
No test file of its own yet.
For information: Footprint
0.8 KB of source (gzip) in 1 file. Installs radix-ui.
Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.
Use with AI
A Radix progress bar with clamped values, optional percentage text, and a reduced-motion-safe pending state. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Progress (@ballmac/progress) to this project with the shadcn MCP, then use it where it fits.
Use it for
- Show completion of a bounded task
- Show work in progress when completion is unknown
Not for
- Use a spinner for very short waits
Registry JSON: https://ui.ballmac.com/r/progress.json
Credits
Based on shadcn/ui Progress, adapted by Ballmac. Free to use in personal and commercial projects.
- npm
- radix-ui
- Registry
- shadcn/utils
Pairs well with
Spinner
A compact loading indicator with three sizes, an accessible label, and reduced-motion behavior.
Alert Dialog
Focus-managed confirmation for consequential actions, with a clear cancel path, optional media, and a token-based destructive action.
Alert
A semantic callout with five theme-aware tones, clear icon placement, an action row, and opt-in urgent announcements.
Banner
A page-wide announcement with semantic tones, optional action, and controlled or local dismissal.
Ballmac UI Pro
Need the whole screen, not one piece?
311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.
Not ready? Try three Pro blocks free
Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.