Feedback

Usage Meter

Linear or circular quota / billing usage indicator with severity tones.

Import

tsx

import { UsageMeter, UsageMeterLinear, UsageMeterCircular } from "@cooud-ui/ui";

bash

npx cooud-ui add usage-meter

Examples

Linear

A horizontal quota bar with a label and a value / max readout. The `auto` tone shades the fill from primary to warning to error as usage climbs.

Tokens186,400 / 250,000 tokens75%

Seats18 / 2090%

Storage48 / 50 GB96%

tsx

<div className="flex w-full max-w-sm flex-col gap-6">
  <UsageMeter label="Tokens" value={186_400} max={250_000} unit="tokens" />
  <UsageMeter label="Seats" value={18} max={20} />
  <UsageMeter label="Storage" value={48} max={50} unit="GB" />
</div>

Circular

An SVG ring for compact, at-a-glance quota — here three API-request budgets.

62%

API requests

6,200 / 10,000

86%

Bandwidth

172 / 200 GB

95%

Builds

95 / 100

tsx

<div className="flex flex-wrap items-center gap-8">
  <UsageMeterCircular label="API requests" value={6_200} max={10_000} />
  <UsageMeterCircular label="Bandwidth" value={172} max={200} unit="GB" tone="warning" />
  <UsageMeterCircular label="Builds" value={95} max={100} />
</div>

API Reference

Generated from the component's exported types.

UsageMeterProps

Extends Omit<HTMLAttributes<HTMLDivElement>, "children">

Prop	Type	Default	Description
`value`*	`number`	—	Current usage.
`max`*	`number`	—	The quota / limit the usage is measured against.
`label`	`ReactNode`	—	Optional label shown beside (linear) or below (circular) the meter.
`unit`	`string`	—	Unit suffix appended to the value readout, e.g. "tokens".
`variant`	`UsageMeterVariant`	`"linear"`	Layout: a horizontal bar or an SVG ring.
`tone`	`UsageMeterTone`	`"auto"`	Color. `auto` derives severity from the usage ratio; others are explicit.
`formatValue`	`(value: number, max: number) => string`	—	Override the `value / max` readout.
`showValue`	`boolean`	`true`	Whether to render the textual value/percentage readout.
`size`	`number`	`96`	Diameter of the ring in px (circular variant only).