# Usage Meter

One limit as a row, or as a budget card: what is used, what is allowed, and a warning before it runs out.

- Category: AI & Agents
- Page: https://wunderui.com/components/usage-meter
- Tier: Core and Pro

## Install

Usage Meter ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { UsageMeter, CostMeter, UsageMeterProps, UsageMeterSize, UsageMeterTone } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { UsageMeter } from "@wunderui/react"

export function TokensToday({ used }: { used: number }) {
  return <UsageMeter label="Tokens today" used={used} limit={1_000_000} unit="tokens" sub="Resets at 00:00 UTC" />
}
```

Expected result: The label and 420k / 1M on one line, a thin bar, then the reset time at the left and 42% used at the right. From 80% the bar turns amber, and above the limit red with Over by.

## When to use

### Use Usage Meter for

- Plan quotas and rate limits: tokens per day, requests per minute, seats, storage
- Several limits stacked in one list, each with its reset time
- A limit that is passed, with the overage written out
- A budget card for what an agent has spent in a run, a day or a month, with a large figure (`variant="card"`)

### Use something else

- [Context Meter](https://wunderui.com/components/context-meter) for how full the model's context window is
- [Meter](https://wunderui.com/components/meter) for any other fixed value within a range

## Behavior

How the meter turns three numbers into a state, a format and a status line, and what it does when the numbers change.

- **State:** The state follows used over limit. Above 1 it is over and red, from the warning threshold (0.8 by default) up to and including the limit it is amber, and below that it is normal.
- **Words and colour:** The state is also written, so colour is never the only signal: N% used, N% · nearly at the limit, Over by 22k tokens. The percentage is rounded but the state isn't, so 79.6% reads 80% used.
- **Overage:** Above the limit the figures, bar and words turn red, the bar stays full and the line reads Over by the difference, followed by the unit if there is one. The percentage is not shown.
- **Zero limit:** A limit of 0 is used up by any use, which reads Over by that use. A use of 0 against a limit of 0 reads 0% used.
- **Number format:** By default 420,000 reads 420k and 1,020,000 reads 1.02M. Pass a format to change how used, limit and the overage are written, and it must return the same text for the same number.
- **Numbers that are not valid:** The meter doesn't check its input. A negative use reads as a negative percentage and a value that isn't a number reads NaN% used with a full bar, so check the data first.
- **Meter semantics:** The bar is a meter from 0 to the limit. Its value is the use capped at the limit, its name is the label and its value text is the status line, so a screen reader reads Tokens today, 42% used.
- **Live updates:** Pass a new used value and the figures, state and fill change at once. Nothing is announced, so put a status line next to the meter, mounted before it has text, and update it.
- **Motion:** Only the fill's width moves, and only when the used value changes. Width is a layout property where the motion rules prefer transform, a known gap, and colours change at once.
- **Reduced motion:** With reduced motion the fill jumps to its new width. The figures and words are the same.
- **Card variant:** The card turns amber at `warnAt` (80 % by default) and red once the budget is reached, and then says so with a warning icon and "Budget reached" or "Nearly spent". A zero budget counts as used up by any spend.

## Anatomy

- `UsageMeter`: One row with no frame of its own. It carries a state of normal, warning or over, for styling and tests.
- `Label`: What the limit is, in 14 px medium text, such as Tokens today. It is the meter's name.
- `Figures`: Used and limit in 12 px medium tabular figures, written by your format. Grey normally, amber near the limit and red over it.
- `Meter bar`: A 6 px track with a fill, exposed as a meter from 0 to the limit. The fill is primary, amber or red, and never grows past the track.
- `Sub-label`: Small print under the bar at the left: when the limit resets or what it covers.
- `Status line`: At the right: N% used, N% · nearly at the limit, or Over by the overage with its unit. It is also the meter's value text.
- `CostMeter`
- `Usage Meter`
- `Cost Meter`

## Best practices

### When to use

- Use it for a limit that can be passed: a plan's quota, a rate limit, seats, storage. For the money a run spends use the card variant, for the context window Context Meter, and for other ranges Meter.

### Do

- Name the limit and its period in the label (Tokens today, Requests per minute) and say when it resets in the sub-label. A limit without a reset reads as permanent.
- Set the unit to the word that follows an overage, such as tokens or requests, so a passed limit reads Over by 22k tokens.
- Pass a format when the short form isn't what you want: full numbers with commas (1,250,000), money ($1,842) or a size (18.4 GB). It formats the figures and the overage.
- Stack several meters with a 16 px gap and keep their labels parallel, so a plan's limits read as one list.
- Announce a change of level in a status line next to the meter. The meter itself isn't a live region.

### Don't

- Don't use a limit of 0 to mean unlimited. Any use against a zero limit reads as over it, so leave the meter out for an unlimited plan.
- Don't draw a meter from missing data. A value that isn't a number reads NaN% used on a full bar, so show a skeleton while it loads and a message when it fails.
- Don't rely on the meter to enforce the limit, since it shows the use and your backend stops the work. Put an action like Upgrade plan next to a meter that is near or over.

## API reference

### UsageMeter

| Prop | Type | Default | Description |
|---|---|---|---|
| limit* | number |  | What is allowed. 0 counts as used up by any use; it does not mean unlimited. |
| used* | number |  | How much has been used, in the unit of the limit. Above the limit the meter reads over it. |
| className | string |  | Extra classes for the row, for example `max-w-sm`. |
| currency | string |  | Card variant only. ISO 4217 code used when `unit` is `currency`. The default is `EUR`. |
| format | (value: number) => string |  | Writes `used`, `limit` and the overage as text. Default: `420k`, `1.02M`. Pass a function for full numbers, money or sizes. |
| label | React.ReactNode |  | What the limit is, such as `Tokens today`. It is the heading of the row and the name of the meter. |
| period | "month" \| "run" \| "day" |  | Card variant only. `run` (default), `day` or `month`. It writes the heading `Spend this run`, `Spend today` or `Spend this month` when there is no `label`. |
| showRemaining | boolean |  | Card variant only. Shows the amount left on the right of the status line while the spend is within budget. Default `true`. The warning and budget-reached words always show. |
| size | "lg" \| "sm" \| "md" |  | The thickness of the bar: `sm` 6 px (default), `md` 8 px or `lg` 10 px. It applies to the row and the card. |
| sub | React.ReactNode |  | Small print under the bar, such as `Resets at 00:00 UTC`. Any node. |
| tone | "purple" \| "orange" \| "primary" |  | Bar colour in the normal state. Default `primary`. |
| unit | string |  | The word after an overage, such as `tokens`, so it reads `Over by 22k tokens`. It shows only when the limit is passed. |
| variant | "row" |  | `row` (default) is one line with the label, the used and allowed amounts, a bar and a status. `card` is the budget card: a heading, the budget, a large figure, a bar, the share used and the amount left, with a warning at `warnAt` and when the budget is reached. In the card, `used` is the amount spent and `limit` the budget. It replaces CostMeter. |
| warnAt | number |  | The share of the limit, from 0 to 1, where the meter turns amber. Default `0.8`. |

### CostMeter

| Prop | Type | Default | Description |
|---|---|---|---|
| budget* | number |  |  |
| spent* | number |  |  |
| className | string |  |  |
| currency | string |  | ISO code, used when `unit` is "currency". |
| label | string |  | Overrides the default "Spend this run" heading. |
| period | "month" \| "run" \| "day" |  |  |
| showRemaining | boolean |  |  |
| unit | "currency" \| "tokens" \| "requests" |  |  |
| warnAt | number |  | Fraction of the budget at which the meter turns amber. |

## Examples

### Format: short, full numbers, money, storage

### Warn at: the share of the limit where the meter turns amber

### Content: label, reset time and overage unit

### Card level: within budget, nearly spent, over

### Card unit: dollars, euros, tokens, requests

### Card warn at: the share of the budget where the meter turns amber

### Card content: heading and remainder

### Tone and size: tint the bar, make it thicker

## In context

### Plan limits: one meter per limit, three plans

The same usage against three plans: 842,000 tokens, 210 requests per minute and 3 agents. The numbers match but the state differs: Starter is over on tokens, Team is near, Scale is fine.

### Live count: a run uses tokens, the status line reports it

The count rises once a second, the meter turns amber at 80%, and at the limit it stops and Upgrade plan raises it. The meter is not a live region, so the status line reports each change.

### States of a usage page: loading, failed, loaded

The meter needs numbers: show rows of the same height while they load, and say so with another try if they cannot be loaded. A meter drawn from missing data would read as an empty limit.

### Card, live run: the spend climbs, the status line reports it

The spend rises once a second and the card turns amber at 80%. At the budget the run pauses until you raise it, and a status line next to the meter says what changed.

### Card, budgets per agent: one meter each

Four agents with monthly budgets: two within budget, one nearly spent and one over. The heading names the agent, so each card reads on its own.

### Card, run panel: state, money and context

The side panel of a running agent: its state and running time, the spend in dollars and the share of the context window in tokens.

## For AI agents

`get_component("usage-meter")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
