Token meter

Free · MIT

Context window usage bar whose segments (system, history, tools, response) spring to new widths, with rolling numbers, a legend, and amber then rose tones near and over the limit.

Markdown Open in v0

Open in v0

Installation

$ npx shadcn@latest add https://goodui.dev/r/token-meter.json

The file lands in components/goodui/token-meter.tsx and is yours to edit. With the @goodui registry added, npx shadcn@latest add @goodui/token-meter works too.

Usage

import { TokenMeter } from "@/components/goodui/token-meter"

<TokenMeter
  label="Context window"
  max={200_000}
  segments={[
    { label: "System prompt", value: 1_240 },
    { label: "History", value: 38_400 },
    { label: "Tool results", value: 6_120 },
    { label: "Response", value: 2_310 },
  ]}
/>

When to use

Use it for

Showing how much of the model's context is used, split into system prompt, history, tool results and the response.
Agent dashboards where the budget matters: it turns amber at 80% and rose at 95% or over.
Per-conversation cost or quota meters with a single number.

Reach for something else

Plan quotas unrelated to tokens (seats, SMS credits): use meter.
Live counting while typing: chat-composer has its own small ring.

If you need	Use
One number	used + max
Breakdown with legend	segments (used is their sum)
Show what is left	showRemaining
Exact numbers	format="full"
Other thresholds	warnAt and dangerAt as fractions of max

Examples

Single value near the limit

<TokenMeter label="Conversation" used={171_300} max={200_000} size="sm" />

Remaining budget in full numbers

<TokenMeter label="Remaining" used={62_500} max={128_000} showRemaining format="full" />

API reference

Prop	Type	Default
max* The context window.	number	—
used Tokens used, when there is one number.	number	—
segments Breakdown by part of the context; used = sum of the values.	TokenSegment[]	—
label	React.ReactNode	—
warnAt Fraction of max where the meter turns amber.	number	0.8
dangerAt Fraction of max where it turns rose.	number	0.95
showLegend Show the segment legend.	boolean	true
showRemaining Show the remaining count instead of used / max.	boolean	false
format Compact (12.4K) or full (12,400) numbers.	"compact" \| "full"	"compact"
size	"sm" \| "md" \| "lg"	"md"
locale	string	"en-US"
labels Text for built-in controls and screen readers; pass translations here.	Partial<TokenMeterLabels>	—

Also accepts every <div> attribute.

The bar is role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and an aria-valuetext such as "38,400 of 200K tokens used. Close to the limit".
The rolling number is aria-hidden; the meter's text carries the value for screen readers. Legend values are plain text.
Built-in strings go through the labels prop for translation.

Motion

Each segment is a flex item sized by its tokens; when values change they spring to their new widths through motion's layout animation (stiffness 260, damping 30).
The used number rolls digit by digit (number-flow, installed alongside).
Reduced motion: widths and digits change instantly.

Notes for AI

Coding agents read these rules through MCP and llms.txt, or paste this page with Copy page.

Pass either used or segments; with segments, used is their sum and the legend lists them with --chart-1..5 colors unless color is set.
max is the context window in tokens. Values above max are shown as over the limit (rose) and the bar is capped.
format="compact" prints 38.4K / 200K; "full" prints 38,400 / 200,000 in the given locale.

FAQ

Can I color a segment?

Yes, segment.color takes any CSS color, for example var(--chart-3) or an oklch value.

Usage meter

Labeled usage meter like "SMS credits 7,420 / 10,000" whose fill springs to the new value and shifts to amber and rose near the limit, with optional per-seat segments.

Progress

Linear progress in four variants: spring-filled determinate, indeterminate double sweep, moving stripes and segmented steps.

Number flow

Digits roll to the new value with locale formatting, prefixes and suffixes.

Chat composer

Prompt input with an auto-growing textarea, attachment chips from picker, paste or drop, a slash-command menu, model and mode selectors, a token ring against the context limit, Enter or Cmd+Enter to send and a Stop button while streaming.