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

Ouvrir Default dans Storybook

With Zones

Ouvrir With Zones dans Storybook

Larger Label

Ouvrir Larger Label dans Storybook

Show Category

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

Ouvrir Show Category dans Storybook

Caption

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

Ouvrir Caption With Badge dans Storybook

Custom Range

Ouvrir Custom Range dans 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.

Ouvrir Fills Its Column dans 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.

Ouvrir Zone Labels Give Way dans 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.

Ouvrir Active Zone Label dans 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.

Ouvrir Formatted Ends dans Storybook

Or pass your own words for the two ends.

Ouvrir Named Ends dans 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.

Ouvrir Ends In A Narrow Column dans 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.

Ouvrir Icon Marker dans 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