ui/components/progress

Progress

Horizontal progress bar with determinate and indeterminate modes, drawn in hard-edged character cells by default. Uses native progressbar ARIA with value clamping and a terminal-inspired sliding animation for indeterminate state.

Preview

tsx

1 import { Progress } from "@/components/ui/progress";2 3 export default function ProgressDefault() {4   return (5     <div className="flex flex-col gap-4 w-64">6       <Progress value={60} aria-label="Upload progress" />7       <Progress aria-label="Loading" />8     </div>9   );10 }11

Installation

$pnpm exec dgadd add ui/progress

[Installs to]src/components/ui/progress[Item]ui/progress

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 import { Progress } from "@/components/ui/progress";2 3 export default function ProgressDefault() {4   return (5     <div className="flex flex-col gap-4 w-64">6       <Progress value={60} aria-label="Upload progress" />7       <Progress aria-label="Loading" />8     </div>9   );10 }11

Examples

Variants

Preview

tsx

1 import { Progress } from "@/components/ui/progress";2 3 export default function ProgressVariants() {4   return (5     <div className="flex w-64 flex-col gap-4">6       <div className="flex flex-col gap-1.5">7         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">8           variant="cells" (default)9         </span>10         <Progress value={45} aria-label="Cell progress" />11       </div>12       <div className="flex flex-col gap-1.5">13         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">14           variant="bar"15         </span>16         <Progress value={45} variant="bar" aria-label="Bar progress" />17       </div>18     </div>19   );20 }21

Sizes

Preview

tsx

1 import { Progress } from "@/components/ui/progress";2 3 export default function ProgressSizes() {4   return (5     <div className="flex w-64 flex-col gap-4">6       <div className="flex flex-col gap-1.5">7         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">8           size="sm"9         </span>10         <Progress value={45} size="sm" aria-label="Small progress" />11       </div>12       <div className="flex flex-col gap-1.5">13         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">14           size="md"15         </span>16         <Progress value={45} size="md" aria-label="Medium progress" />17       </div>18     </div>19   );20 }21

Labeled with value text

Preview

tsx

1 "use client";2 3 import { useId } from "react";4 import { Progress } from "@/components/ui/progress";5 6 export default function ProgressLabeled() {7   const labelId = useId();8 9   return (10     <div className="flex w-72 flex-col gap-1.5">11       <div className="flex items-baseline justify-between font-mono text-xs">12         <span id={labelId} className="text-foreground">13           Uploading diffs14         </span>15         <span className="text-muted-foreground">3/5</span>16       </div>17       <Progress value={3} max={5} aria-labelledby={labelId} valueText="3 of 5 diffs uploaded" />18     </div>19   );20 }21

API Reference

Progress

Name	Type	Default	Description
value	number	—	Current progress value (0-100). Omit for indeterminate mode.
max	number	100	Finite positive maximum for the progress bar. Invalid values are normalized to 100.
size	"sm" \| "md"	"md"	Height of the progress bar track. "sm" renders as the continuous bar.
variant	"cells" \| "bar"	"cells"	"cells" cuts track and fill into hard-edged character cells. "bar" keeps the continuous rounded track for hairline-thin inline uses.
valueText	string	—	Custom text exposed through aria-valuetext for the current value.

Data attributes

Attribute	Applies to	Values	Description
data-state	Progress	"loaded" \| "indeterminate"	Determinate/indeterminate state for track and indicator styling.
data-variant	Progress	"cells" \| "bar"	Selects the cell mask or the continuous track.
data-size	Progress	"sm" \| "md"	Track height; "sm" suppresses the cell mask.

CSS variables

Name	Default	Description
--progress-cell	8px	Width of one cell in the cells variant, including its gap.
--progress-gap	1px	Width of the knocked-out gap between two cells.

Accessibility

Notes

Indeterminate Mode

When value is undefined, the bar enters indeterminate mode with a sliding fill animation. The aria-valuenow attribute is omitted per WAI-ARIA spec.

Value Clamping

The value is clamped between 0 and max. Values outside this range are silently corrected. A NaN value is normalized to 0 before clamping. A non-finite, zero, or negative max is normalized to the default of 100 before ARIA values and fill width are calculated.

Cells vs Bar

variant="cells" (default) masks track and fill into --progress-cell wide cells, so Progress speaks the same quantity language as BlockBar. The mask lives on the root, so the cells stay phase-aligned as the fill grows and the leading edge fills them one by one. variant="bar" keeps the continuous rounded track for hairline-thin inline uses. size="sm" is a 4px track — below the useful cell threshold — so it renders as the continuous bar even under variant="cells".

Reduced Motion

The indeterminate animation respects prefers-reduced-motion: reduce. When active, the bar renders a static 40% fill, and the determinate fill stops animating its width.

Progress vs BlockBar

Progress is the pixel bar for task completion: role=progressbar, a solid fill, and an indeterminate mode for work with no known duration. BlockBar is the character-cell meter for a steady-state measurement (role=meter) — coverage, token budget, severity mix — drawn from filled/empty glyphs and stackable into colored segments. Reach for Progress when something is running, BlockBar when something is being measured.

Source

Install via CLI: pnpm exec dgadd add ui/progress.

Highlighted source loads after this disclosure opens. Browse the source repository.

Progress

Installation

Usage

Examples

Variants

Sizes

Labeled with value text

API Reference

Progress

Data attributes

CSS variables

Accessibility

Notes

Indeterminate Mode

Value Clamping

Cells vs Bar

Reduced Motion

Progress vs BlockBar

Source

View component source (7 files)