MeterGroup

An unstyled meter group component for visualizing scalar measurements within a range.

Build fully custom meter visualizations with complete control over layout and styling.

Apps (16%)
Messages (8%)
Media (24%)
System (10%)

basic-demo

Pre-styled Versions

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

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

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

Features#

Compound component API with sub-components: Root, Meters, Meter, Labels, Label, Marker, Icon, Text
Built-in color palette with 9 named colors that cycle automatically via index
Percentage calculation relative to configurable min/max bounds
Horizontal and vertical orientation for both meters and labels

Usage#

import { MeterGroup } from 'primereact/metergroup';

<MeterGroup.Root>
    <MeterGroup.Meters>
        <MeterGroup.Meter />
    </MeterGroup.Meters>
    <MeterGroup.Labels>
        <MeterGroup.Label>
            <MeterGroup.Marker />
            <MeterGroup.Text></MeterGroup.Text>
        </MeterGroup.Label>
    </MeterGroup.Labels>
</MeterGroup.Root>

Behavior#

Polymorphic Rendering#

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

<MeterGroup.Root as="section"></MeterGroup.Root>
<MeterGroup.Labels as="ul"></MeterGroup.Labels>
<MeterGroup.Label as="div"></MeterGroup.Label>

Default elements: Root=div, Meters=div, Meter=div, Labels=ol, Label=li, Marker=span, Icon=Icon, Text=span.

Render Function Children#

Root accepts a render function as children, providing access to the component instance.

<MeterGroup.Root>{(instance) => <span>Total: {instance.state.totalPercent}%</span>}</MeterGroup.Root>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

Space used (15%)

/* Select a part to see its CSS selector for custom styling */

API#

MeterGroupRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupRootInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupRootPassThrough>`	—
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: MeterGroupRootInstance) => 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.
`min`	`number`	`0`
Minimum boundary value.
`max`	`number`	`100`
Maximum boundary value.
`orientation`	`"horizontal"` \| `"vertical"`	`horizontal`
Specifies the layout of the component.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"metergroup"`
`data-part`	`"root"`
`data-orientation`	Current orientation value

Defines passthrough(pt) options of MeterGroup component.

label	type	description
root	MeterGroupRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
meters	MeterGroupRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the meters' DOM element.
meter	MeterGroupRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the meter's DOM element.
labels	MeterGroupRootPassThroughType<HTMLAttributes<HTMLOListElement>>	Used to pass attributes to the labels' DOM element.
label	MeterGroupRootPassThroughType<HTMLAttributes<HTMLLIElement>>	Used to pass attributes to the label's DOM element.
icon	MeterGroupRootPassThroughType<HTMLAttributes<HTMLElement>>	Used to pass attributes to the label icon's DOM element.
marker	MeterGroupRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the label marker's DOM element.
text	MeterGroupRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

MeterGroupMeters#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupMetersInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupMetersInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupMetersInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupMetersPassThrough>`	—
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: MeterGroupMetersInstance) => 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`	`"metergroup"`
`data-part`	`"meters"`

Defines passthrough(pt) options of MeterGroupMeters component.

label	type	description
root	MeterGroupMetersPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

MeterGroupMeter#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupMeterInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupMeterInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupMeterInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupMeterPassThrough>`	—
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: MeterGroupMeterInstance) => 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`	`number`	—
Defines the value of the meter.
`color`	`string & {}` \| `METERGROUP_DEFAULT_COLORS_TYPE`	—
Defines the color of the meter.
`index`	`number`	—
Defines the index of the meter.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"metergroup"`
`data-part`	`"meter"`

Defines passthrough(pt) options of MeterGroupMeter component.

label	type	description
root	MeterGroupMeterPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

MeterGroupLabels#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupLabelsInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupLabelsInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupLabelsInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupLabelsPassThrough>`	—
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: MeterGroupLabelsInstance) => 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.
`orientation`	`"horizontal"` \| `"vertical"`	`horizontal`
Specifies the label orientation of the component.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"metergroup"`
`data-part`	`"labels"`

Defines passthrough(pt) options of MeterGroupLabels component.

label	type	description
root	MeterGroupLabelsPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

MeterGroupLabel#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupLabelInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupLabelInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupLabelInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupLabelPassThrough>`	—
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: MeterGroupLabelInstance) => 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.
`color`	`string`	—
Defines the color of the label.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"metergroup"`
`data-part`	`"label"`

Defines passthrough(pt) options of MeterGroupLabel component.

label	type	description
root	MeterGroupLabelPassThroughType<HTMLAttributes<HTMLLIElement>>	Used to pass attributes to the root's DOM element.

MeterGroupMarker#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupMarkerInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupMarkerInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupMarkerInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupMarkerPassThrough>`	—
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: MeterGroupMarkerInstance) => 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.
`color`	`string & {}` \| `METERGROUP_DEFAULT_COLORS_TYPE`	—
Defines the color of the marker.
`index`	`number`	—
Defines the index of the marker.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"metergroup"`
`data-part`	`"marker"`

Defines passthrough(pt) options of MeterGroupMarker component.

label	type	description
root	MeterGroupMarkerPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

MeterGroupIcon#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupIconInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupIconInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupIconInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupIconPassThrough>`	—
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: MeterGroupIconInstance) => 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`	`"metergroup"`
`data-part`	`"icon"`

Defines passthrough(pt) options of MeterGroupIcon component.

label	type	description
root	MeterGroupIconPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

MeterGroupText#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: MeterGroupTextInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: MeterGroupTextInstance) => string)`	—
The class name to apply to the component.
`as`	`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`	`MeterGroupTextInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<MeterGroupTextPassThrough>`	—
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: MeterGroupTextInstance) => 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`	`"metergroup"`
`data-part`	`"text"`

Defines passthrough(pt) options of MeterGroupText component.

label	type	description
root	MeterGroupTextPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

MeterGroup component uses meter role in addition to the aria-valuemin, aria-valuemax and aria-valuenow attributes. Value to describe the component can be defined using aria-labelledby prop.

Keyboard Support#

Component does not include any interactive elements.