Progress

Determinate and indeterminate progress—with subtle motion.

Installation

npx shadcn@latest add @iconiq/r-progress

File Structure

Usage

"use client";

import { useEffect, useState } from "react";
import { Progress } from "@/components/ui/r-progress";

const frames = [8, 14, 22, 31, 42, 55, 68, 80, 90, 96, 88, 76];

export function ProgressPreview() {
  const [frameIndex, setFrameIndex] = useState(0);

  useEffect(() => {
    const interval = window.setInterval(() => {
      setFrameIndex((current) => (current + 1) % frames.length);
    }, 340);

    return () => window.clearInterval(interval);
  }, []);

  return (
    <Progress
      className="w-full max-w-sm"
      helper="Smooth width animation keeps the bar and inline readout aligned as work advances."
      label="Registry sync"
      value={frames[frameIndex]}
    />
  );
}

Props

Props
Description

Progress

value

Current progress value. Pass null to switch into the indeterminate motion state instead of rendering a measured fill width.

Type number | null·Default 0

min

Lower bound used to normalize the fill width and the visible value text.

Type number·Default 0

max

Upper bound used to normalize the fill width and the visible value text.

Type number·Default 100

label

Optional title rendered above the bar and linked to the progress semantics when present.

Type string

helper

Optional supporting copy rendered near the label for extra task context. When omitted, the header collapses down to just the label and trailing value readout.

Type string

showValue

Controls whether the trailing inline readout with the live formatted value or indeterminate label is shown.

Type boolean·Default true

formatValue

Optional formatter for the visible value readout. Receives the current normalized value and percent so you can render units, fractions, or custom labels.

Type (value: number, percent: number) => string

getValueLabel

Optional formatter for screen-reader announcements when the accessible text should be more explicit than the visible readout.

Type (value: number, percent: number) => string

indeterminateLabel

Text used for the visible value readout and accessible status when value is null.

Type string·Default "In progress"

ariaLabel

Accessible name used when no visible label is rendered. When omitted, unlabeled installs fall back to a generic Progress label.

Type string

className

Merged onto the root wrapper so you can control width, spacing, or placement in your layout.

Type string

variant

Linear bar (default) or circular gauge layout with a dual-stroke ring, 5% gap, and CSS-smoothed arc transitions. Circular mode renders the value readout centered inside the ring.

Type "default" | "circular"·Default "default"

size

Track height preset for the default bar, or ring diameter preset for the circular variant.

Type "sm" | "md" | "lg"·Default "md"

tone

Fill color preset for neutral, brand, destructive, or success emphasis.

Type "default" | "brand" | "destructive" | "success"·Default "default"

trackClassName

Merged onto the track element for custom track styling.

Type string

indicatorClassName

Merged onto the fill element for custom indicator styling.

Type string

headerClassName

Merged onto the label, helper, and value readout row above the track.

Type string

Motion and semantics

Headless progress semantics from the provider primitive with a spring-smoothed fill and restrained indeterminate motion layered on top.

Built on Radix Progress.Root and Progress.Indicator while the visible fill and inline value readout stay under the same minimal Motion shell as the Base UI version.

Determinate mode uses a spring-smoothed width animation instead of a hard width jump, which keeps status updates feeling more fluid when values change rapidly.

Indeterminate mode uses one minimal left-to-right flow band with a soft fade at the start and end of each pass, so the restart stays visually quiet.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @radix-ui/react-progress, motion.

Installs a Radix progress bar with the same value, min, max, label, helper, indeterminate, and formatter API as the Base UI version.

Uses the Radix progress primitive under the same spring-smoothed track fill and restrained inline readout motion shell.

The generated registry file is /r/r-progress.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

Registry sync

Smooth width animation keeps the bar and inline readout aligned.

64%