Progress Bar

Overview

ProgressBar is the shared horizontal progress indicator used to show completion, loading progress, or proportional values.

It renders a role="progressbar" element with automatic aria-valuenow derived from value and max.

Use ProgressBar for linear progress within forms, task lists, upload flows, and reading indicators. For compact circular progress, use ProgressCircle.

Basic Usage

import { ProgressBar } from '@fsai/shared-ui';

<ProgressBar value={60} color="blue" size="sm" />

With A Fraction Label

const completed = 7;
const total = 12;

<div className="flex items-center gap-2">
  <ProgressBar
    value={completed}
    max={total}
    color="green"
    size="sm"
    className="flex-1"
  />
  <span className="whitespace-nowrap text-sm tabular-nums text-minimal">
    {completed}/{total}
  </span>
</div>

Transparent Track Overlay

Use trackColor="transparent" when the bar sits on top of other content, such as a reading-progress indicator pinned to the top of an article.

<div className="relative h-32 overflow-hidden rounded-xl border border-alpha-default">
  <ProgressBar
    value={42}
    color="blue"
    size="xs"
    trackColor="transparent"
    className="absolute left-0 top-0"
  />
  {/* content below */}
</div>

Mount Animation

Use animateIn for a fill-in animation on mount via framer-motion:

<ProgressBar
  value={75}
  color="blue"
  size="md"
  animateIn
  animateInDelay={0.2}
/>

Props

Prop	Type	Default	Description
`value`	`number`	—	Required. Current progress value.
`max`	`number`	`100`	Upper bound for deriving fill percentage.
`color`	`'blue' \| 'green' \| 'gray' \| 'red' \| 'orange'`	`'gray'`	Fill color.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg'`	`'sm'`	Bar thickness (`h-1` through `h-3`).
`trackColor`	`'neutral' \| 'transparent'`	`'neutral'`	Track background treatment.
`minVisibleFill`	`number`	`0`	Minimum rendered fill % when `value > 0`, so small amounts remain visible.
`animated`	`boolean`	`true`	CSS width transition on value changes.
`animateIn`	`boolean`	`false`	Animate fill from 0 on mount via framer-motion.
`animateInDelay`	`number`	`0`	Delay in seconds before mount animation.
`aria-label`	`string`	—	Accessible label. Defaults to `"N%"`.
`className`	`string`	—	Additional classes on the root.

Important Conventions

Values are clamped to 0–100% based on value / max.
minVisibleFill is ignored when value is exactly 0.
When animateIn is true, it drives width animation instead of the CSS animated transition.
Prefer pairing with a numeric label when the exact value matters to the user.

Guidelines

Do use ProgressBar for linear completion and proportional values
Do use minVisibleFill when small non-zero values would otherwise be invisible
Do use trackColor="transparent" for overlay-style indicators
Don't use ProgressBar for indeterminate loading — use Spinner or Skeleton
Don't use ProgressBar when a compact circular indicator is enough — use ProgressCircle

Progress Bar

On this page