Usage Meter
ProOne limit as a row: what is used, what is allowed, a bar and a status line that warns before the limit and says by how much it was passed.
Playground
Tokens today
420k / 1M
Tokens this month
420k / 1M
Tokens
420k / 1M
Tokens today
860k / 1M
Tokens this month
860k / 1M
Tokens
860k / 1M
Tokens today
1.02M / 1M
Tokens this month
1.02M / 1M
Tokens
1.02M / 1M
Installation
Usage Meter comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
UsageMeter,
CostMeter,
UsageMeterProps,
UsageMeterSize,
UsageMeterTone,
} from "@wunderui/react"Then use it:
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 ()
Use something else for
- Context Meter for how full the model's context window is
- Meter for any other fixed value within a range
Format
The default writes 420k and 1.25M. A format function gives full numbers with commas (1,250,000), money ($1,842) or a size (18.4 GB) for the used amount, the limit and the overage.
Tokens today
1.25M / 2M
Tokens today
1,250,000 / 2,000,000
Spend this month
$1,842 / $2,500
Storage
18.4 GB / 20.0 GB
Warning threshold
The warning threshold is a share of the limit between 0 and 1. From there the bar and figures turn amber and the line says the limit is near; above the limit they turn red.
Warn at
Tokens today
850k / 1M
Tokens today
850k / 1M
Tokens today
850k / 1M
Content
The label names the limit. The sub line is small print under the bar, the place for when it resets, and the unit is the word after an overage, such as Over by 20k tokens.
Requests per minute
210 / 500
Requests per minute
210 / 500
Tokens this month
18.4M / 18M
Card
variant="card" is the budget card for what an agent has spent in a run, a day or a month: a heading, the budget, the amount as a large figure, a bar, the share used and the amount left. In the card, used is the amount spent and limit the budget. The level follows from the two numbers: amber at warnAt (80 % by default, with Nearly spent), red at the budget (Budget reached). The unit sets how numbers are written: money shows two decimals under 10 and whole units from 10 up, tokens are shortened from 1,000, requests are written in full. The heading says what the spend is for, and showRemaining hides the amount left while the warning stays. It replaces CostMeter.
Card level
Spend today
$50 budget
$21
Spend today
$50 budget
$43
Spend today
$50 budget
$58
Card unit
Spend this month
$2,500 budget
$1,843
Spend this month
€2,500 budget
€1,843
Context used
200k tokens budget
128k
Spend today
1,000 requests budget
860
Card warn at
Spend this month
$2,000 budget
$1,700
Spend this month
$2,000 budget
$1,700
Spend this month
$2,000 budget
$1,700
Card content
Spend this month
$2,500 budget
$1,040
Collections agent
$2,500 budget
$1,040
Spend this month
$2,500 budget
$1,040
Tone and size
tone colours the bar while the meter is normal (primary, purple or orange) so several limits can be told apart; amber and red for warning and over always win. size="lg" makes the bar 10 px. In the card variant the currency defaults to USD.
Seats
12 / 30
Storage
18 GB / 50 GB
API requests
142k / 500k
Tokens today
4.2M / 10M
Behavior and motion
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 (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
The figure marks the meter within its limit. Nearly at the limit and over the limit change the colours and words of parts 3 and 6, not the parts.
Tokens today
420k / 1M
- 1
One row with no frame of its own. It carries a state of normal, warning or over, for styling and tests.
- 2
What the limit is, in 14 px medium text, such as Tokens today. It is the meter's name.
- 3
Used and limit in 12 px medium tabular figures, written by your format. Grey normally, amber near the limit and red over it.
- 4
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.
- 5Optional
Small print under the bar at the left: when the limit resets or what it covers.
- 6
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.
- data-slot="usage-meter"
- data-slot="cost-meter"
- Optional
Best practices
- 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.
- Do
Set the unit to the word that follows an overage, such as tokens or requests, so a passed limit reads Over by 22k tokens.
- Do
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.
- Do
Stack several meters with a 16 px gap and keep their labels parallel, so a plan's limits read as one list.
- Do
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
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
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 is a plain component, not a wrapper of a primitive, so this table lists every prop. `variant="card"` is the budget card with a large figure, the period, the amount left and a warning (it replaces CostMeter): it takes `used` and `limit` like the row, plus `unit` (`currency`, `tokens` or `requests`), `currency`, `period`, `label` and `showRemaining`.
One row with no frame of its own. It carries a state of normal, warning or over, for styling and tests.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | ReactNode | — | What the limit is, such as . It is the heading of the row and the name of the meter. |
| used required | number | — | How much has been used, in the unit of the limit. Above the limit the meter reads over it. |
| limit required | number | — | What is allowed. 0 counts as used up by any use; it does not mean unlimited. |
| unit | string | — | The word after an overage, such as , so it reads . It shows only when the limit is passed. |
| sub | ReactNode | — | Small print under the bar, such as . Any node. |
| warnAt | number | — | The share of the limit, from 0 to 1, where the meter turns amber. Default . |
| format | (value) => string | — | Writes , and the overage as text. Default: , . Pass a function for full numbers, money or sizes. |
| size | "lg" | "sm" | "md" | — | The thickness of the bar: 6 px (default), 8 px or 10 px. It applies to the row and the card. |
| className | string | — | Extra classes for the row, for example . |
| variant | "row" | — | (default) is one line with the label, the used and allowed amounts, a bar and a status. is the budget card: a heading, the budget, a large figure, a bar, the share used and the amount left, with a warning at and when the budget is reached. In the card, is the amount spent and the budget. It replaces CostMeter. |
| currency | string | — | Card variant only. ISO 4217 code used when is . The default is . |
| period | "month" | "run" | "day" | — | Card variant only. (default), or . It writes the heading , or when there is no . |
| showRemaining | boolean | — | Card variant only. Shows the amount left on the right of the status line while the spend is within budget. Default . The warning and budget-reached words always show. |
| tone | "purple" | "orange" | "primary" | — | Bar colour in the normal state. Default . |
| Prop | Type | Default | Description |
|---|---|---|---|
| budget required | number | — | |
| spent required | number | — | |
| currency | string | — | ISO code, used when 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. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("usage-meter")The full library index for assistants is at /llms.txt.