useProgressBar

Usage#

import { useProgressBar } from '@primereact/headless/progressbar';

const { rootProps, trackProps, state } = useProgressBar({ value: 50 });
 
<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#

• Value normalization — state.computedValue converts any raw value in the min/max range into a 0-100 percentage
• Formatted display text — state.formattedValue renders via a default percent formatter or your custom one
• ARIA attributes — rootProps carries aria-valuenow, aria-valuemin, and aria-valuemax
• Custom range — configurable min and max with a console error guard when bounds are invalid
• Reactive state — state is safe to read from custom labels or indicators that sit outside the track

Working with callbacks#

Working with a custom range#

Set min and max to match your data model. The returned computedValue is always expressed as a percentage so your styles stay range-agnostic.

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

Custom formatted labels#

Pass a formatter to control the text rendered in state.formattedValue. Handy for fractional, ratio, or localized displays.

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

Rendering a label alongside the track#

Read state.computedValue and state.formattedValue to render progress text wherever you need it — no extra calls required.

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

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#

Accessibility#

Value is exposed via aria-valuenow, aria-valuemin, and aria-valuemax for screen readers. See Primitive for full WAI-ARIA compliance details.