Meter

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

Show a measurement within a known range, such as memory or storage usage. Show the value with its unit. low, high and optimum split the range as the native meter element does: the fill keeps its color in the best range and turns caution one range away and danger two. Target marks a goal across the track, and Tick marks the scale under it; both are named in the meter's description. Meter.Arc draws the meter as a half circle with a needle, in place of Track, such as an indicator on a card: low, high and optimum split it into zones with a small gap at each threshold, in the status marks, and a zone too narrow to draw is a dot.

Use Progress, not Meter, for task completion or loading of unknown length. Don't make users judge risk from color alone. Describe the risk in text too.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root → Label + Value + Track(Indicator + Target? + Tick*) | Arc (svg, aria-hidden: a zone per range + needle)

Keyboard and accessibility

Meter is a read-only measurement and isn't in the Tab order. Describe what it measures and its unit in Label and aria-valuetext. In RTL, the fill still grows from the logical start.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Meter } from '@surflane/ui'

<Meter.Root value={30} min={0} max={64} aria-valuetext='30 GiB of 64 GiB'>
  <Meter.Label>Memory allocation</Meter.Label>
  <Meter.Value>{(_, value) => `${value} / 64 GiB`}</Meter.Value>
  <Meter.Track>
    <Meter.Indicator />
  </Meter.Track>
</Meter.Root>

// Lower is better: past 40 GiB the fill turns caution, past 56 danger.
<Meter.Root value={46} max={64} low={40} high={56} optimum={0}>…</Meter.Root>

<Meter.Root value={34} aria-valuetext='34%'>
  <Meter.Label>Bonds in the portfolio</Meter.Label>
  <Meter.Track>
    <Meter.Indicator />
    <Meter.Target value={40} label='Target 40%' />
    <Meter.Tick value={50} />
  </Meter.Track>
</Meter.Root>

// A half circle in its ranges: lower is calmer.
<Meter.Root value={17.2} min={10} max={40} low={20} high={30} optimum={10} aria-valuetext='17.2, calm'>
  <Meter.Label>VIX volatility index</Meter.Label>
  <Meter.Value>{(_, value) => value.toFixed(1)}</Meter.Value>
  <Meter.Arc />
</Meter.Root>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens