smooth-progress

A minimal, beautifully animated progress bar component library for React. Smooth transitions, spring physics, and multiple visual variants — all under 5KB gzipped.

Install

pnpm add smooth-progress

Quick Start

import { ProgressBar } from "smooth-progress";

function App() {
  return <ProgressBar value={65} />;
}

Components

ProgressBar

Linear progress bar with smooth width transitions.

<ProgressBar value={75} variant="gradient" size="md" />
<ProgressBar value={50} spring duration={300} />
<ProgressBar indeterminate variant="glow" />

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | number | — | Progress value (0–100) | | max | number | 100 | Maximum value | | variant | "default" \| "gradient" \| "glow" \| "striped" \| "pulse" | "default" | Visual style | | size | "xs" \| "sm" \| "md" \| "lg" | "md" | Height preset | | showLabel | boolean | false | Show percentage inside bar | | spring | boolean | false | Use spring physics | | duration | number | 250 | Transition duration (ms) | | color | string | — | Custom fill color | | indeterminate | boolean | false | Loading state |

ProgressCircle

Circular progress indicator with animated stroke.

<ProgressCircle value={80} size="lg" showLabel />
<ProgressCircle value={45} color="#10b981" spring />
<ProgressCircle indeterminate size="sm" />

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | number | — | Progress value (0–100) | | size | "sm" \| "md" \| "lg" \| "xl" | "md" | Diameter preset | | strokeWidth | number | auto | Stroke width in px | | showLabel | boolean | false | Show percentage in center | | spring | boolean | false | Use spring physics | | color | string | — | Custom stroke color | | indeterminate | boolean | false | Spinning loading state |

ProgressSteps

Multi-step progress with animated transitions.

<ProgressSteps
  steps={[
    { label: "Cart" },
    { label: "Shipping" },
    { label: "Payment" },
    { label: "Done" },
  ]}
  currentStep={2}
/>

Animation Philosophy

Built on principles from animations.dev:

• ease-in-out for on-screen morphing (progress fill changes)
• ease-out for elements entering (checkmarks, step completions)
• Spring physics option for interruptible, natural transitions
• GPU-accelerated — uses scaleX transforms instead of width
• Reduced motion — fully respects prefers-reduced-motion
• Under 300ms — all transitions stay within perceptible UI range

Styling

Works with Tailwind CSS out of the box. Uses CSS variables for theming:

• --primary — default fill color
• --foreground — label text
• --muted-foreground — secondary text

For the striped animation, import the companion CSS:

import "smooth-progress/styles.css";

License

MIT