Usage Meter

A row of token, cost, and capacity readouts for chat surfaces.

Anatomy

Drop a meter wherever the call site wants to surface usage. A session footer with totals, a per-message footer with the cost of one call, or a status row that pairs a context-window bar with a few stats. The meter wraps when space runs out and stays unobtrusive on dark or light surfaces.

For a context-window readout, mix in a UsageBar. Pass the label row as children, the bar handles clamping and the over-capacity color shift.

Formatting

The meter never formats values. Pass already-formatted strings to UsageStatValue and the bar's label children. The kit leaves the choice of locale, decimal places, and currency to the call site so the same component works for tokens, requests, dollars, or any other counter.

Streaming values

For counters that update mid-stream, drop an AnimatedNumber inside UsageStatValue or a bar's label. The number tweens from its previous value to the new one each time the prop changes, so a token meter wired to a streaming hook reads as a continuous counter rather than a flicker of discrete updates. Pass a format callback to control the rendered text on every frame.

AI integrations

Use size="sm" to drop the meter into a message footer next to MessageText. The smaller size keeps the meter from inflating the bubble, and the wrap behavior keeps a long stat row from pushing the message wider than its neighbors. See the per-message demo for the pattern.

API

Reference for each part of the component, including its available props and behavior.

UsageMeter

Root row. Lays the stats and bars out inline with a wrap, and seeds the density for descendants via the size prop. The sm size tightens the gap, drops to text-xs, and thins the bar track so it sits comfortably inside a message footer.

UsageStat

A label and value pair. Composes its own children so the call site decides the order, the formatting, and whether to add an icon or a tooltip. Pair with UsageStatLabel and UsageStatValue for the default tone treatment.

UsageStatLabel

The descriptor side of a stat. Muted by default. Override with className when a stat needs to stand out.

UsageStatValue

The number side of a stat. Foreground tone, medium weight, and tabular numerals so values stay aligned across rows that animate.

AnimatedNumber

Tweens between numeric values with an ease-out cubic curve. Drop it inside UsageStatValue or a bar's label to give a streaming counter a continuous feel. Renders a <span> with tabular numerals so the digits stay aligned mid-tween. The format callback runs on every frame, so currency, decimal places, and locale all stay on the caller.

UsageBar

A horizontal capacity bar built on Base UI's Meter. The fill width is clamped to the [0, max] range, so a value of zero shows an empty track and a value at or above max shows a full bar. The bar exposes a data-state attribute that flips to over when the fill reaches eighty percent of capacity, swapping the fill from the primary accent to the destructive tone for an at-a-glance warning. Children render as a label row above the track. The element carries role="meter" and the matching aria-value* attributes for assistive tech, and forwards any other Base UI Meter.Root prop (aria-label, aria-valuetext, format, etc.).