DocsComponents

Progress bar

Linear and circular indicators with precise Material motion.

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/progress-bar.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Use determinate when progress is known, and indeterminate when the duration is unknown. min and max define the range. Supply an aria-label describing the operation.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

ProgressBar never advances a value itself. Use mode="determinate" with value, min, and max for measured progress. buffer describes buffered progress for the linear indicator.

The default indeterminate mode communicates ongoing work without a known amount. Give the indicator an accessible name in either mode.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`ProgressBar`

Property	Type	Default
`buffer`	`number`	`0`
`disabled`	`boolean`	`—`
`max`	`number`	`100`
`min`	`number`	`0`
`mode`	`'determinate' \| 'indeterminate'`	`'indeterminate'`
`multicolor`	`boolean`	`false`
`classNames`	`ProgressBarTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`ProgressBarTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`type`	`'linear' \| 'circular'`	`'linear'`
`value`	`number`	`0`
`ref`	`Ref<HTMLDivElement>`	`—`

Also inherits HTMLAttributes<HTMLDivElement>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Additional defaults on inherited props: className = ''.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

buffer
circle
circular
circular-indeterminate-bar-dash
circular-indeterminate-bar-rotate
colors
indeterminate
linear
linear-indeterminate-bar
multicolor
path
value

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/progress-bar.

ProgressBarProps

tsx

interface ProgressBarProps extends HTMLAttributes<HTMLDivElement> {
  buffer?: number;
  disabled?: boolean;
  max?: number;
  min?: number;
  mode?: 'determinate' | 'indeterminate';
  multicolor?: boolean;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: ProgressBarTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: ProgressBarTheme;
  type?: 'linear' | 'circular';
  value?: number;
  ref?: Ref<HTMLDivElement>;
}

ProgressBarTheme

tsx

type ProgressBarTheme = Partial<
  Record<
    | 'buffer'
    | 'circle'
    | 'circular'
    | 'indeterminate'
    | 'linear'
    | 'multicolor'
    | 'path'
    | 'value'
    | 'linear-indeterminate-bar'
    | 'circular-indeterminate-bar-rotate'
    | 'circular-indeterminate-bar-dash'
    | 'colors',
    string
  >
>;

ProgressBarClassNames

tsx

type ProgressBarClassNames = ProgressBarTheme;

Material guidelines

Use a determinate indicator when the amount of work is known, and an indeterminate indicator when it is unknown. The examples show separate operations.
Use one indicator per operation. Keep determinate progress moving forward and label the operation so its meaning does not depend on motion alone.

Material Design 1: Progress and activity