UsageMeter

A segmented meter that shows what fills a fixed allowance, how much is free, and how close it is to the limit.

When to use

• Plan allowances such as storage, seats, or monthly pageviews, broken down by what uses them.
• Billing and settings pages where people decide what to clean up or whether to upgrade.
• Not for task completion: use Progress. Not for a single metric over time: use MetricCard or a chart.

Usage

import { UsageMeter } from "@/components/iris/usage-meter/usage-meter";

h(UsageMeter, {
  label: "Anasa Cloud storage",
  unit: "GB",
  limit: 5,
  segments: [
    { id: "notes", label: "Notes", value: 0.6 },
    { id: "daily", label: "Daily notes", value: 0.4 },
    { id: "boards", label: "Boards", value: 0.2 },
  ],
});

Props

Prop	Type	Default	Description
label	string	—	Required. What is measured.
segments	{ id: string; label: string; value: number }[]	—	Required. Used amounts in display order; up to four read clearly. Keep ids stable so segments re-flow when values change.
limit	number	—	Required. The plan limit, in the same unit.
unit	string	""	Unit shown after numbers.
decimals	number	1	Digits after the decimal point.
freeLabel	string	"Free"	Legend label for the remaining space.
overLabel	string	"Over limit"	Label for usage past the limit.
warnAt	number	0.9	Share of the limit at which the badge switches to "Almost full".

Notes

• The status badge reads "{n} free", "Almost full", or "{n} over"; status changes are announced through a polite live region.
• The bar is an image with a full text summary; legend items are buttons (aria-pressed) that highlight and pin their segment.
• Segment widths and numbers spring to new values; reduced motion updates instantly.
• Reads --accent (and tints of it for later segments), --red, --orange, --surface, --hover, --line-strong, --ink, --ink-2.