PrimeUI PRO for React is now available 🚀View Demos

ProgressSpinner

An unstyled, accessible circular progress component with compound composition.

Build fully custom circular progress indicators with complete control over track, range, and value rendering.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use ProgressSpinner with ready-made designs.

Theme-based styling with CSS variables

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with four sub-components: Root, Track, Range, Value
SVG-based circular geometry with automatic radius and circumference calculation
Determinate mode with stroke dash animation and indeterminate mode with CSS-driven animation
Configurable min, max, and strokeWidth

Usage#

import { ProgressSpinner } from 'primereact/progressspinner';

<ProgressSpinner.Root>
    <ProgressSpinner.Track />
    <ProgressSpinner.Range />
</ProgressSpinner.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered element.

<ProgressSpinner.Root as="section">
    <ProgressSpinner.Track />
    <ProgressSpinner.Range />
    <ProgressSpinner.Value as="span" />
</ProgressSpinner.Root>

Default elements: Root=div, Track=circle, Range=circle, Value=text.

Render Function Children#

Value accepts a render function as children, providing access to the component instance. The instance exposes progressspinner (root instance with state.percent and state.indeterminate).

<ProgressSpinner.Value>{(instance) => <tspan>{Math.round(instance.progressspinner?.state.percent ?? 0)}%</tspan>}</ProgressSpinner.Value>

Pass Through#

The component's PT demo referenced as progressspinner-pt is unavailable or does not exist.

API#

ProgressSpinnerRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ProgressSpinnerRootInstance) => undefined` \| `CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ProgressSpinnerRootInstance) => undefined` \| `string)`	—
The class name to apply to the component.
`as`	`null` \| `string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ProgressSpinnerRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ProgressSpinnerRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ProgressSpinnerRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`value`	`null` \| `number`	—
Current value. When null, the component is in indeterminate mode.
`min`	`number`	`0`
Minimum value.
`max`	`number`	`100`
Maximum value.
`strokeWidth`	`number`	`4`
Width of the circle stroke.
`disabled`	`boolean`	`false`
Whether the component is disabled.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"progress"`
`data-part`	`"root"`
`data-state`	`"determinate"` or `"indeterminate"`
`data-value`	Current value (determinate only)
`data-disabled`	Present when disabled

ProgressSpinnerTrack#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ProgressSpinnerTrackInstance) => undefined` \| `CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ProgressSpinnerTrackInstance) => undefined` \| `string)`	—
The class name to apply to the component.
`as`	`null` \| `string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ProgressSpinnerTrackInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ProgressSpinnerTrackPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ProgressSpinnerTrackInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"progress"`
`data-part`	`"circleTrack"`
`data-state`	`"determinate"` or `"indeterminate"`

ProgressSpinnerRange#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ProgressSpinnerRangeInstance) => undefined` \| `CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ProgressSpinnerRangeInstance) => undefined` \| `string)`	—
The class name to apply to the component.
`as`	`null` \| `string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ProgressSpinnerRangeInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ProgressSpinnerRangePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ProgressSpinnerRangeInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"progress"`
`data-part`	`"circleRange"`
`data-state`	`"determinate"` or `"indeterminate"`

ProgressSpinnerValue#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ProgressSpinnerValueInstance) => undefined` \| `CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ProgressSpinnerValueInstance) => undefined` \| `string)`	—
The class name to apply to the component.
`as`	`null` \| `string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ProgressSpinnerValueInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ProgressSpinnerValuePassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ProgressSpinnerValueInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Accessibility#

ProgressSpinner uses role="progressbar" on the root element. In determinate mode, aria-valuemin, aria-valuemax, and aria-valuenow describe the current progress. Provide aria-label or aria-labelledby to give the component an accessible name.

<ProgressSpinner.Root aria-label="Loading">
    <ProgressSpinner.Track />
    <ProgressSpinner.Range />
</ProgressSpinner.Root>
 
<ProgressSpinner.Root value={75} aria-label="Upload progress">
    <ProgressSpinner.Track />
    <ProgressSpinner.Range />
    <ProgressSpinner.Value />
</ProgressSpinner.Root>

Keyboard Support#

ProgressSpinner is a non-interactive display component and does not receive keyboard focus.