Meter

Every example on this page is live, drawn by the library's Storybook, where you can also change its props and see the result.

A linear gauge bar with pattern fills to differentiate zones.

Import

import { Meter } from "~lib/data-display/meter";

Props

Name	Type	Required	Default	Description
value	number	Yes	N/A	Current value
min	number	No	0	Minimum value
max	number	No	100	Maximum value
zones	{ end: number; pattern: PatternType; label?: string }[]	No	N/A	Zone segments
labels	"auto" | "all" | "active" | "none"	No	"auto"	Which zone labels to show under the bar
label	string	No	N/A	Label above meter
labelSize	"xs" | "sm" | "base"	No	"xs"	Size of the label, value and end labels
caption	ReactNode	No	N/A	Content shown above the meter in place of the label
showValue	boolean	No	true	Show numeric value
showCategory	boolean	No	false	Show the label of the zone the value falls in, instead of the number
format	(value: number) => string	No	N/A	Writes the numbers the meter prints, such as a price with its currency
ends	"none" | "values" | { min: string; max: string }	No	"none"	What to print under the two ends of the bar
marker	IconName | ReactElement	No	N/A	An Icon or a small node drawn on the bar in place of the triangle
markerBearing	number	No	N/A	Degrees clockwise to turn an icon marker, for the way it faces
width	number | string	No	200	Width in px, or a CSS width such as "100%"

Examples

Default

Open Default in Storybook

With Zones

Open With Zones in Storybook

Larger Label

Open Larger Label in Storybook

Show Category

With showCategory, the meter names the zone the value falls in (here "Moderate") instead of printing the number.

Open Show Category in Storybook

Caption

Pass caption to put your own content above the bar, such as a name beside a Badge.

Open Caption With Badge in Storybook

Custom Range

Open Custom Range in Storybook

Filling a Column

Set width="100%" to make the meter as wide as whatever it sits in. The bar always meets the column's edges, while the marker and the zone names keep their size.

Open Fills Its Column in Storybook

Zone Labels That Give Way

By default the zone names show only when there is room for them. While every name fits under its zone without running into the next one, they all show; when they would touch, only the name of the zone the marker is in shows, kept inside the bar; and when even that name is wider than the bar, none show. The space under the bar stays the same height either way, so the meter is just as tall in a narrow column.

Open Zone Labels Give Way in Storybook

Set labels to "all", "active" or "none" to choose yourself. "active" names only the zone the value is in, which suits a meter whose reading already says the number.

Open Active Zone Label in Storybook

Formatting the Value

Pass format to write the value the way the rest of your widget writes it. It gets the number and returns the text to print, so a price can be grouped, rounded and followed by its currency.

const usd = new Intl.NumberFormat("en-US", { maximumFractionDigits: 0 });

<Meter
  value={price}
  min={dayLow}
  max={dayHigh}
  label="Today's range"
  format={(value) => `${usd.format(value)} USD`}
  ends="values"
/>;

Labeling the Ends

Set ends="values" to print min and max under the two ends of the bar, written with format, so a reader knows what the bar runs between.

Open Formatted Ends in Storybook

Or pass your own words for the two ends.

Open Named Ends in Storybook

The end labels keep their size when the meter fills a column. Where the meter is too narrow for both of them, only the one nearer the marker is shown.

Open Ends In A Narrow Column in Storybook

An Icon for a Marker

marker draws something in place of the triangle: an Icon by its name, such as a plane flying along a flight's progress between its airports, or a small node of your own. It sits on the bar at the value, in a square as tall as the inside of the bar on the background, so it reads over the bar's fill and its zones, and it stays inside the bar's ends at either extreme, at a pixel width and across a column alike. markerBearing turns an icon that many degrees clockwise, for the way it faces. The meter is as tall as it is with the triangle.

Open Icon Marker in Storybook

<Meter
  value={flight.flownKm}
  max={flight.distanceKm}
  marker="plane"
  ends={{ min: flight.from, max: flight.to }}
  showValue={false}
  width="100%"
/>

See Also

• ProgressRing - Circular progress
• BarIndicator - Simple bar indicator
• LevelIndicator - A scale of equal bands, such as an air quality index