Meter

A meter shows a measurement in a known range, like disk usage, battery level, or a score. Give it thresholds and it turns green, amber, or red by how good the reading is. For a task that moves toward completion, use Progress instead.

Preview#

import {
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,

Installation#

npxnpx shadcn@latest add @cubby-ui/meter

Usage#

import {
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,
} from "@/components/ui/cubby-ui/meter/meter";

<MeterRoot>
  <MeterLabel />
  <MeterValue />
  <MeterTrack>
    <MeterIndicator />
  </MeterTrack>
</MeterRoot>

Composition#

MeterRoot
├── MeterLabel
├── MeterValue
├── MeterTrack
│   └── MeterIndicator
└── MeterTargetRange

The root puts the label and value on the first row and spans everything else below, so you don't need a wrapper.

Examples#

Sizes#

Use size to set the track thickness.

import {
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,

Variants#

Use variant to set the indicator color for a meter without thresholds.

import {
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,

Once you set thresholds, the status colors take over.

Thresholds#

Use low and high to split the range into three regions, and optimum to mark the best one, as on the native <meter>.

import {
  type MeterStatus,
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterTargetRange,

A reading in the optimum's region is green, the next region amber, and the far region red. A notch marks each threshold on the track.

Target Range#

Add MeterTargetRange after the track to underline the range from low to high when optimum sits between them. Leaving out optimum counts, since it defaults to the midpoint of min and max.

import {
  type MeterStatus,
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterTargetRange,

Live Readings#

Update value as often as you like; the indicator eases to each reading and fades its color across thresholds.

"use client";
 
import * as React from "react";
import {
  MeterRoot,
  MeterTrack,

Segments#

Set segments on MeterTrack to split the track into equal blocks, which replace the threshold notches.

import {
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,

Custom Range and Format#

Use min, max, and format to measure in your own units.

import {
  MeterRoot,
  MeterTrack,
  MeterIndicator,
  MeterLabel,
  MeterValue,

Accessibility#

Screen readers skip MeterValue and read the root's value text, and they can't see the status color. getAriaValueText receives the status as a third argument, so you can announce it:

getAriaValueText={(formatted, _value, status) =>
  status === "critical" ? `${formatted}, critical` : formatted
}

With reduced motion on, the indicator jumps between values instead of easing.

API Reference#

The Meter component is built on top of Base UI's Meter. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Meter documentation.

Props#

MeterRoot#

Holds the value, works out the status, and lays out the parts. Wraps Base UI's Meter.Root.

MeterTrack#

The full range of the meter. Wraps Base UI's Meter.Track.

MeterTargetRange#

A line under the track spanning low to high, shown when optimum sits between them, including the default midpoint. A plain <div>, hidden from screen readers, so state the range in text too. Meter always renders it; to leave it out, compose the parts without it.

MeterIndicator#

The filled part of the track, colored by status. Wraps Base UI's Meter.Indicator.

Data Attributes#

CSS Variables#