useMeterGroup

Usage#

import { useMeterGroup } from '@primereact/headless/metergroup';
 
const { rootProps, percent, percentAsString } = useMeterGroup();
 
return <div {...rootProps}></div>;

useMeterGroup tracks cumulative meter values and converts them to percentages within min/max bounds — see Primitive for a component-based API.

Features#

• Returns spread-ready rootProps with role="meter", ARIA value attributes, and data-orientation
• Calculates percentage of individual meter values relative to the min/max range
• Tracks aggregated totalPercent across all meters via updateTotalPercent
• Provides percent and percentAsString methods for rendering meter widths
• Supports vertical and horizontal orientation

Behavior#

Default Range#

The default range is 0 to 100. A meter with value: 25 renders at 25% width.

const { percent, percentAsString } = useMeterGroup();
 
percent(25); // 25
percentAsString(25); // '25%'

Custom Range#

Set min and max to change the value boundaries. Percentages are recalculated against the new range.

const { percent } = useMeterGroup({ max: 200 });
 
percent(50); // 25

Orientation#

Set orientation to switch between horizontal and vertical layouts.

const { rootProps } = useMeterGroup({ orientation: 'vertical' });
 
rootProps['data-orientation']; // 'vertical'

Tracking Total Percent#

Call updateTotalPercent to accumulate values across meters. The state.totalPercent reflects the running total.

const { state, updateTotalPercent, resetTotalPercent } = useMeterGroup();
 
updateTotalPercent(15);
updateTotalPercent(25);
state.totalPercent; // 40
 
resetTotalPercent();
state.totalPercent; // 0

Custom Styling with Data Attributes#

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

[data-scope='metergroup'][data-part='root'] {
    display: flex;
    flex-direction: column;
    gap: 0.75rem;
}
 
[data-scope='metergroup'][data-orientation='vertical'] {
    flex-direction: row;
}

API#

useMeterGroup#

Accessibility#

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