progress

Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.

Philosophy

Progress bars answer the most anxious user question: "Is this working?" A determinate progress indicator builds trust by showing measurable advancement. We keep the API to a single value prop because progress is inherently one-dimensional - the component's visual treatment handles the rest.

Installation

npx @gentleduck/cli add progress

npx @gentleduck/cli add progress

Usage

import { Progress } from "@/components/ui/progress"

<Progress value={33} />

RTL Support

Set the direction once with DirectionProvider (or <html dir="rtl">) and Progress fills from the right. No dir prop or rtl: classes needed.

Motion

Alpha: Motion Compositions

Motion components work standalone, but some compositions may behave unexpectedly: this is still under active development. If you find a broken composition, please file an issue.

Use MotionProgress for smooth value animations powered by motion. The bar scales in from the start edge and fades to full opacity over a 0.6s eased transition when the value changes, with a continuously looping shimmer highlight layered on top.

Requires the motion package. Use MotionProgress instead of Progress. Same props. The regular Progress is perfectly fine - this is an optional enhancement.

API Reference

Progress

Prop	Type	Default	Description
`value`	`number`	(required)	Progress value from `0` to `100` representing the completion percentage
`dir`	`'ltr' \| 'rtl'`	-	Text direction. Resolved by primitives `useDirection` (`dir` prop -> `DirectionProvider` -> `<html dir>`).
`className`	`string`	`--`	Additional CSS classes for the progress bar container
`...props`	`Omit<React.HTMLProps<HTMLDivElement>, 'value'>`	-	Additional props to spread to the content div

MotionProgress

Prop	Type	Default	Description
`value`	`number`	(required)	Progress value from `0` to `100`. Value changes animate the bar's scale and opacity over a 0.6s eased transition (not a spring). Includes a continuously looping shimmer overlay.
`dir`	`'ltr' \| 'rtl'`	-	Text direction. Resolved by primitives `useDirection` (`dir` prop -> `DirectionProvider` -> `<html dir>`).
`className`	`string`	-	Additional CSS classes for the progress bar container
`...props`	`Omit<React.HTMLProps<HTMLDivElement>, 'value'>`	-	Additional props to spread to the content div