Meter

Segments

Each segment is a share of max, stacked from the start of the bar. A solid fill shows what is spent, and ink stripes show what is held, committed but not gone. The rest of the track is the frame color. Anything past max is clipped, and a segment with no room left is not drawn.

import { Card, Meter } from '@snapshot-ui/react';
import type { ReactElement } from 'react';

export default function MeterBasic(): ReactElement {
  return (
    <div className="sample-column">
      <Card>
        <Meter
          label="Groceries"
          max={1200}
          segments={[
            { value: 820, look: 'fill', label: 'Spent', valueLabel: '$820.00' },
            { value: 200, look: 'hatched', label: 'Held', valueLabel: '$200.00' },
          ]}
          valueLabel="$1,020 of $1,200"
        />
      </Card>
    </div>
  );
}

Pace and legend

pace places a marker where spending would be today if it kept pace. hasLegend adds a row under the bar naming each segment with its value, then the marker.

import { Card, Meter } from '@snapshot-ui/react';
import type { ReactElement } from 'react';

export default function MeterPace(): ReactElement {
  return (
    <div className="sample-column">
      <Card>
        <Meter
          label="Transport"
          max={400}
          segments={[
            { value: 210, look: 'fill', label: 'Spent', valueLabel: '$210.00' },
            { value: 40, look: 'hatched', label: 'Held', valueLabel: '$40.00' },
          ]}
          valueLabel="$250 of $400"
          pace={{ value: 260, label: "Where you'd be today: $260" }}
          hasLegend
        />
      </Card>
    </div>
  );
}

Over the limit

When the segments add up to more than max, both looks turn the warning color and the bar fills to its end. valueLabel must say "over" in words, such as "$340 of $300, $40 over", since color is never the only signal.

import { Card, Meter } from '@snapshot-ui/react';
import type { ReactElement } from 'react';

export default function MeterOver(): ReactElement {
  return (
    <div className="sample-column">
      <Card>
        {/* Over the limit the bar turns the warning color, and the words say so: color is never the only signal. */}
        <Meter
          label="Dining out"
          max={300}
          segments={[
            { value: 280, look: 'fill', label: 'Spent', valueLabel: '$280.00' },
            { value: 60, look: 'hatched', label: 'Held', valueLabel: '$60.00' },
          ]}
          valueLabel="$340 of $300, $40 over"
          hasLegend
        />
      </Card>
    </div>
  );
}

On another surface

The cut between segments and the ring around the pace marker use --meter-surface, which defaults to Lifted, the card a meter usually sits on. On the page itself, set --meter-surface: var(--color-canvas) on the meter or any ancestor, and every meter inside follows. A DataTable sets it for you, to each row's own fill, hovered and selected included.

.budget-section {
  --meter-surface: var(--color-canvas);
}

Meter or Gauge

Both are meters: a measurement of the reader's state on a known range. Meter is a bar for a row or a list, with segments that stack, such as spent and held, and a pace marker. Gauge is one value drawn as a ring or a semicircle, for a glance: a credit score with its word under it, a utilization in a table row. Meter's range starts at 0 and ends at max, since its segments stack; Gauge's runs from minValue to maxValue, so a score can run from 300 to 850. A meter's cuts and pace ring take --meter-surface; a gauge's marks stand in gaps its svg cuts out, so it needs no surface color. Work getting done is neither: that is a ProgressBar.

Usage

Pass every figure as a formatted string. The library formats no numbers, so the server's HTML is final in any locale. The meter is static, so a server component renders it with no client JavaScript.

import { Meter } from '@snapshot-ui/react';

<Meter
  label="Groceries"
  max={1200}
  segments={[
    { value: 820, look: 'fill', label: 'Spent', valueLabel: '$820.00' },
    { value: 200, look: 'hatched', label: 'Held', valueLabel: '$200.00' },
  ]}
  valueLabel="$1,020 of $1,200"
  pace={{ value: 900, label: "Where you'd be today: $900" }}
  hasLegend
/>;

Props

Meter accepts every HTML element attribute, on its root. The name (aria-label or aria-labelledby) goes on the bar.

Accessibility

The bar is a role="meter" from 0 to max, named by the label or aria-label.

• Its value is read as valueLabel, never as a percentage. The visible value text is hidden, since the meter reads it.
• The pace label is read as its description.
• The legend is a plain list outside the meter, since a meter's children are presentational.
• It takes no focus and has no keys.

Design rules

What keeps meters in the system.