useProgressBar

Hook that normalizes progress values to a percentage range and provides ARIA attributes.

50%

basic-demo

Usage#

import { useProgressBar } from '@primereact/headless/progressbar';
 
const { rootProps, trackProps, state } = useProgressBar({ value: 50 });
 
return (
    <div {...rootProps}>
        <div {...trackProps}>
            <div style={{ width: state.computedValue + '%' }}></div>
        </div>
    </div>
);

useProgressBar normalizes a value within min/max bounds and returns spread-ready prop objects with ARIA attributes — see Primitive for a component-based API.

Features#

Returns spread-ready rootProps and trackProps for root and track elements
Normalizes value to a 0-100 percentage via state.computedValue
Formats display text via configurable formatter function
Validates min < max with console error on invalid bounds

Behavior#

Default Range#

The default range is 0 to 100. Set value to reflect current progress.

const { state } = useProgressBar({ value: 75 });
 
state.computedValue; // 75
state.formattedValue; // '75%'

Custom Range#

Set min and max to define custom bounds. The value is normalized to a 0-100 percentage.

const { state } = useProgressBar({ value: 50, min: 0, max: 200 });
 
state.computedValue; // 25

Custom Formatter#

Pass a formatter function to control display text. It receives the computed percentage.

const { state } = useProgressBar({
    value: 50,
    formatter: (value) => `${value}/100`
});
 
state.formattedValue; // '50/100'

Using `state` for Custom UI#

The hook exposes reactive state for rendering custom indicators.

const { state } = useProgressBar({ value: 75 });
 
<span>{Math.round(state.computedValue ?? 0)}%</span>
<span>{state.formattedValue}</span>

Custom Styling with Data Attributes#

The prop objects include data-scope="progressbar" and data-part for styling.

[data-scope='progressbar'][data-part='root'] {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
}
 
[data-scope='progressbar'][data-part='track'] {
    height: 1.25rem;
    border-radius: 9999px;
    overflow: hidden;
}

API#

useProgressBar#

Name	Type	Default
`value`	`number`	—
Current value of the progress.
`max`	`number`	—
Defines the mode of the progress
`min`	`number`	—
Defines the mode of the progress
`formatter`	`(value: number) => string`	—
Custom formatter function to format the display value

Accessibility#

See ProgressBar Primitive for WAI-ARIA compliance details and keyboard support.