ProgressBar supplies a horizontal appearance for Progress. It preserves the complete root contract, including native attributes, refs, render composition, formatting, custom ranges, and indeterminate progress. Give it an aria-label that identifies the operation.
Usage
State ownership and ranges
value is required and controlled by the application. There is no defaultValue mode. The component does not start a request or advance progress by itself. Pass null when progress is unknown. Non-finite values also remain indeterminate.
min defaults to 0, and max defaults to 100. Finite values are clamped to the range for the semantic value and normalized fill. A value of 70 in the range 20 to 120 fills half the bar and reports 50%, while aria-valuenow stays 70.
Use aria-valuetext, getAriaValueText, locale, and format as described in Progress. Use composed Progress parts when labels and values need their own visible layout.
Use Toast for notifications with a dismiss countdown and hover pause.
Appearance and composition
size selects a 6px or 8px track. barColor and backgroundColor accept CSS colors, including theme variables. withBorderRadius rounds the track and indicator. withMinimumFillWidth keeps a small cosmetic fill only between the minimum and completion. This minimum is at most 12px and half the track width, so a narrow track still distinguishes incomplete progress from completion. It does not fill an empty bar or change semantic values.
Native attributes, className, style, and ref target the root. className and style can receive the progress state. render can replace the root while preserving its semantics. Indeterminate progress has its own appearance without reporting a numeric percentage. Reduced-motion preferences disable fill transitions and indeterminate motion.
Compose Progress parts for custom layouts or feature animation. Feature timing, grow-in, glints, springs, and completion callbacks belong to the application composition.
Migration
ReplaceariaLabel with native aria-label. The withGrowIn, withGlint, withSpringFill, and onGrowInComplete props are removed. Implement their appearance, timing, and completion callbacks in an application composition using Progress parts. Native onAnimationEnd remains available on the root.
Props
string
Accessible name identifying the measured operation.
string
ID of the visible label that names the operation.
string
Human-readable progress value overriding the default formatted value.
string
default:"none"
CSS background color of the track.
string
CSS color of the filled bar. Defaults to the primary text color.
ReactNode
Additional Progress parts or supporting content inside the root.
string | ((state: ProgressRootState) => string | undefined)
Class applied to the progress root, or a callback receiving its status.
NumberFormatOptions
Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
((formattedValue: string, value: number | null) => string)
Receives the formatted value and raw value, including null, and returns an accessible value description.
LocalesArgument
Locale or locale list used to format the value. Defaults to the runtime locale.
number
default:"100"
Inclusive maximum. Defaults to 100.
number
default:"0"
Inclusive minimum. Defaults to 0.
Ref<HTMLDivElement>
Ref to the root div, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>
Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.
"md" | "sm"
default:"md"
Bar height: sm (6px) or md (8px).
CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)
Inline styles applied to the progress root, or a callback receiving its status.
number | null
required
Controlled value in the min/max range. Use null for indeterminate progress.
boolean
default:"false"
Rounds the track and indicator corners.
boolean
default:"true"
Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion.