Progress React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Usage

Import Progress from @/components/ui/progress.

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

export function ClientImport({ done, total }: { done: number; total: number }) {
  return (
    <div className="flex flex-col gap-4">
      <Progress
        label="Importing clients"
        description={`${done} of ${total} rows`}
        value={done}
        max={total}
        showValue
      />
      <Progress
        label="Storage"
        value={7.2}
        max={10}
        thresholds={{ warning: 80, danger: 95 }}
        showValue
        formatValue={(value, max) => `${value} GB of ${max} GB`}
      />
      <ProgressRing value={68} tone="brand" showValue aria-label="Monthly goal" />
    </div>
  )
}

Props

• valuedefault 64
  number | null

  The current value, from 0 to max. Omit it (or pass null, NaN) for the indeterminate state: a sliding bar or a spinning arc. Values outside 0..max are clamped for drawing. The playground starts at a sample 64; the component's default is null.

• maxdefault 100
  number

  The value that means done. 0 or less renders the indeterminate state.

• variantdefault "linear"
  "linear" | "segmented" | "ring"

  linear: one bar. segmented: equal steps (onboarding, password strength, stories); a fractional value fills a segment partly. ring: a circle for KPIs and compact rows.

• segmentsdefault 5
  number

  Segmented only: how many equal steps. 2,5 of 5 shows two full segments and one half.

• sizedefault "md"
  "xs" | "sm" | "md" | "lg"

  Linear track 2 / 4 / 6 / 8px (xs is the hairline for a refreshing list); ring 24 / 32 / 48 / 64px with a 3 / 3 / 4 / 6px stroke. The xs ring shows its value beside it.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The fill color. The track stays a neutral tint. A finished upload does not turn green on its own: pass success when it should.

• colordefault ""
  string

  Any CSS color for the fill; replaces the tone. Empty uses the tone.

• radiusdefault "full"
  "none" | "sm" | "full"

  Ends of the linear and segmented bars: square, 2px or a pill.

• labeldefault ""
  ReactNode

  Above the bar, or beside the ring with labelPosition side. Names the progressbar for screen readers (else pass aria-label).

• descriptiondefault ""
  ReactNode

  Under the bar in small muted text, e.g. "2.4 MB of 12 MB". Linked with aria-describedby.

• showValuedefault false
  boolean

  Shows the formatted value at the end of the header row (linear) or in the center of the ring.

• valueFormatdefault "percent"
  "percent" | "fraction" | "value"

  How the value reads: "64%", "32 / 50" or "32", in the locale ("64 %" in de-DE).

• labelPositiondefault "top"
  "top" | "side"

  Ring only: top stacks label, ring and description; side puts the text to the right of the ring (KPI rows).

• stripeddefault false
  boolean

  Linear only: moving diagonal stripes on the fill while it is below max. They stop under reduced motion.

• animateddefault true
  boolean

  Value changes glide on a spring. Off, the bar jumps straight to the new value.

• localedefault ""
  string

  Intl locale for the value. Empty uses the UIProvider locale, then the page language.

• thresholds
  { warning?: number; danger?: number }

  Quotas: at or above warning % the fill turns warning, at danger % danger. Compares percentages, not raw values. Wins over tone and color.

• bufferdefault 0
  number

  Linear only: a lighter second bar behind the fill, in the same units as value (media buffering, uploaded vs processed). Glides on the same spring. Omitted (0 in the playground) draws none.

• thicknessdefault 0
  number

  Ring only: the stroke width in px. 0 uses 3 / 3 / 4 / 6px by size.

• formatValue
  (value: number, max: number) => ReactNode

  Replaces valueFormat, e.g. "7.2 GB of 10 GB".

• getValueLabel
  (value: number, max: number) => string

  The aria-valuetext. Defaults to the percent in the locale.

• children
  ReactNode

  Ring only: replaces the centered value (an icon, a figure in your own style).

• classNames
  Partial<Record<"header" | "label" | "value" | "track" | "indicator" | "segment" | "ring" | "description", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last. Other props (aria-label, aria-labelledby, aria-describedby) reach the progressbar.

Parts

FAQ

Used in

More React feedback components