Meter

Meters display a scalar value within a known range, using color to signal whether it's optimal, suboptimal, or least optimal.

Storage used

Usage

forge-meter shows a scalar value within a min/max range through value, tickmarks, and an optional low/high/optimum split that colors the track green, yellow, or red depending on where value falls. Reach for a meter when the value is a relatively static data point, like a storage quota or a satisfaction score — for a task’s busy or in-progress state, use linear progress instead; despite the visual similarity, the two represent fundamentally different things.

Rules

Always give a meter an accessible label, either via a label element association or aria-label/aria-labelledby.

Set optimum so the meter's color reflects whether the current value is actually good, not just its raw position in the range.

Pair a grouped meter with a key labeling each meter's color and value.

Don't

Don't use a meter to represent a task's busy or loading state — use linear progress instead.

Don't segment a meter (low/high) and group it at the same time — grouped meters can't be segmented.

Don't rely on color alone to convey a segmented meter's optimal/suboptimal/least-optimal state.

Segmented

Set low and high to divide the track into three regions — below low, between low and high, and above high — colored green, yellow, or red depending on which region optimum falls in relative to value. low must be greater than or equal to min and less than high; high must be less than or equal to max and greater than low.

A segmented meter, colored by how close its value is to the optimum region.

<forge-meter id="meter" low="0.33" high="0.67" optimum="1">
  <label for="meter">
    Label
  </label>
</forge-meter>

Tickmarks

Set tickmarks to show evenly spaced marks along the track; control how many with the --forge-meter-tickmarks token.

A meter with tickmarks along its track.

<forge-meter id="meter" tickmarks style="--forge-meter-tickmarks: 9;">
  <label for="meter">
    Label
  </label>
</forge-meter>

Grouped

Wrap same-range meters in forge-meter-group to lay them out together on a single shared track — useful for parts of a whole. Grouped meters can’t be segmented, and every meter in the group must share the same min/max. Pair a grouped meter with a key labeling each meter’s color and, optionally, its value.

Several related meters grouped on one shared track.

<forge-meter-group id="meter-group">
  <label slot="label" for="meter-group">
    Label
  </label>
  <forge-meter id="meter-1" value="0.25" style="--forge-meter-color: #1E88E5; --_meter-z-index: 3; --_meter-inset: 0%;">
  </forge-meter>
  <forge-meter id="meter-2" value="0.15" style="--forge-meter-color: #FDD835; --_meter-z-index: 2; --_meter-inset: 25%;">
  </forge-meter>
  <forge-meter id="meter-3" value="0.35" style="--forge-meter-color: #43A047; --_meter-z-index: 1; --_meter-inset: 40%;">
  </forge-meter>
</forge-meter-group>
<forge-key style="margin-block-start: 8px;">
  <forge-key-item style="--forge-key-item-icon-color: #1E88E5;">
    <label for="meter-1">
      First
    </label>
    <span slot="value">
      25%
    </span>
  </forge-key-item>
  <forge-key-item style="--forge-key-item-icon-color: #FDD835;">
    <label for="meter-2">
      Second
    </label>
    <span slot="value">
      15%
    </span>
  </forge-key-item>
  <forge-key-item style="--forge-key-item-icon-color: #43A047;">
    <label for="meter-3">
      Third
    </label>
    <span slot="value">
      35%
    </span>
  </forge-key-item>
</forge-key>

Meters display a scalar value within a defined range.

import "@tylertech/forge/meter";

Properties

Property	Attribute	Type	Default	Description
`value`	`value`	`number`	`0`	The current value of the meter.
`min`	`min`	`number`	`0`	The minimum value of the meter.
`max`	`max`	`number`	`1`	The maximum value of the meter.
`low`	`low`	`number \| null \| undefined`	`0`	The low value threshold.
`high`	`high`	`number \| null \| undefined`	`1`	The high value threshold.
`optimum`	`optimum`	`number \| null \| undefined`	`1`	Indicates the region of the optimum value.
`tickmarks`	`tickmarks`	`boolean`	`false`	Whether to display tickmarks.
`valueMode`	`value-mode`	`MeterValueMode`	`'manual'`	Whether the current value is displayed as a percentage or raw value. When set to `'manual'` the value text is not shown automatically but can still be set manually via the value slot.
`direction`	`direction`	`MeterDirection`	`'horizontal'`	Whether the meter is oriented horizontally or vertically.
`shape`	`shape`	`MeterShape`	`'default'`	The shape of the meter.
`innerShape`	`inner-shape`	`MeterInnerShape`	`'default'`	The shape of the bar.
`density`	`density`	`MeterDensity`	`'medium'`	The density of the meter.
`theme`	`theme`	`MeterTheme`	`'default'`	The theme of the meter.
`muted`	`muted`	`boolean`	`false`	Whether the theme is muted.
`percentage`	—	`number`	—	Gets the percentage of the meter that's filled.
—	`aria-valuetext`	`string`	—	Defines a text alternative for the current value. Set this if it would be inaccurate to read the value as a percentage.

Slots

Name	Description
`(default)`	The default slot for the meter's label.
`value`	A textual representation of the meter's value.

CSS Parts

Name	Description
`::part(root)`	The root container element.
`::part(track)`	The element comprising the meter's background.
`::part(bar)`	The bar representing the value.

CSS Custom Properties

Name	Description
`--forge-meter-background`	The background color of the meter.
`--forge-meter-color`	The color of the meter's bar.
`--forge-meter-height`	The block size of the meter.
`--forge-meter-shape`	The border radius of the meter.
`--forge-meter-bar-inner-shape`	The border radius of the meter's bar.
`--forge-meter-tickmarks`	The number of tickmarks to display.
`--forge-meter-tickmark-opacity`	The opacity of the tickmarks.
`--forge-meter-transition-duration`	The duration of transitions.
`--forge-meter-transition-timing`	The timing function of transitions.
`--forge-theme-success`	The color of the bar when the value is optimal.
`--forge-theme-success-container-low`	The color of the track when the value is optimal.
`--forge-theme-warning`	The color of the bar when the value is suboptimal.
`--forge-theme-warning-container-low`	The color of the track when the value is suboptimal.
`--forge-theme-error`	The color of the bar when the value is least optimal.
`--forge-theme-error-container-low`	The color of the track when the value is least optimal.

Labeling

Always give a meter an accessible label — associate it with a <label> element, or set aria-label/aria-labelledby directly. Text placed in the meter’s label slot isn’t accessible on its own; it still needs to be linked to the meter one of those ways. For a grouped meter, also provide a key naming each meter’s color and, optionally, its value.

Automatic ARIA

The meter automatically applies ARIA attributes reflecting its value, min, and max. If the value isn’t naturally a percentage — a discrete count, or a textual quantifier like “low”/“medium”/“high” — set aria-valuetext to a string describing how it should be read instead.