Skip to content
Atomus

Context meter

Shows how full the model’s context window is and what the conversation cost. The compact ring sits in the Prompt input; click it for the breakdown. It turns warning at 80% and error at 95%, with a sentence that says what happens next.

Compact — 84% (open) · 24% · 97%
Bar — side panels
Context window48.2K / 200K
Input
39.2K
Output
6.8K
Tools
2.2K
Cost
$0.184
variant="compact" at 84% (open), 24% and 97% · variant="bar" with breakdown and costLive · light and dark follow the theme switch

Add the source to a shadcn project

npx shadcn@latest add https://docs.atomus.io/r/ai-context-meter.jsonOpen in v0

Installs the component source, its CSS and the Atomus tokens into components/atomus/. How the registry works

In Figma

Section titled “In Figma”

From guidelines/components/ai-context-meter.md

Properties, variants and anatomy of the Figma components. React props use the same names.

Context meter

Section titled “Context meter”

How much of the model’s context window a conversation uses, and what it has cost. The compact style is a ring and percentage for the Prompt input; it opens a card with the bar, a breakdown (input, output, tools) and the cost. The bar style shows the same details inline. Part of the Agent kit.

Figma: component set Context meter on the 🤖 Agent kit page of Atomus 4.0 (node 25546:320), connected to React with Code Connect. React props use the same names as the Figma properties below.

Property Type / options
Used number (tokens)
Limit number (tokens)
Cost number + currency
Breakdown list (label, tokens)
Style Compact · Bar
State Default · Warning (80%) · Error (95%)

State

  • Below warnAt (80%) the fill uses --gradient-ai.
  • From 80% it turns fg-warning with “Getting full: start a new chat for a new topic.”
  • From 95% it turns fg-error with “Almost full: older messages will be summarised or dropped.”

Use for

  • Power-user and developer tools where people manage long conversations or pay per token.

Not for

  • Consumer chat where tokens mean nothing to people — explain limits in words instead.
  • Upload or task progress: use Progress bar.

Accessibility

  • The bar is a WAI-ARIA meter with a text value: “24% used, 48.2K of 200K tokens”.
  • The compact trigger is a button named with the same text; its card closes with Esc.
  • Warning and error states add a sentence, not only a colour.

Usage

Section titled “Usage”
import { ContextMeter } from '@stanvision/atomus-react';


<ContextMeter
  used={usage.totalTokens}
  limit={200000}
  cost={usage.costUsd}
  breakdown={[{ label: 'Input', tokens: usage.input }, { label: 'Output', tokens: usage.output }]}
/>

Props at a glance

Section titled “Props at a glance”

Full types and defaults are in React API at the end of the page.

  • used, limit (tokens), cost and currency, breakdown.
  • variant — compact (ring + %, details on click) or bar.
  • warnAt (80) sets the warning threshold; error is fixed at 95%. locale formats numbers.

Design guidance

Section titled “Design guidance”

From the Figma guidelines.

Do

  • Format large numbers compactly (48.2K) and show cost in the person’s currency.
  • Explain what happens when the window is full.

Forbidden

  • Never block sending when the meter is full without saying why and what to do.

React API

Section titled “React API”

Generated from react/src/components by scripts/gen-react-api.mjs — the same tables agents read in guidelines/components/ai-context-meter.md.

Use only these props; anything else is not part of the API.

ContextMeter

Section titled “ContextMeter”

Figma: Context meter — how much of the model’s context window a conversation uses, and what it cost. A WAI-ARIA meter; the compact variant is a button that opens the details.

import { ContextMeter } from '@stanvision/atomus-react'; — source: react/src/components/ai/ContextMeter.tsx

Prop Type Default Description
used number required Figma: Used — tokens in the context window now
limit number required Figma: Limit — the model’s context window in tokens
cost number — Figma: Cost — spend for this conversation, in currency
currency string 'USD' ISO 4217 currency of cost
breakdown ContextUsagePart[] — Optional split of used (input, output, cached …) shown in the details
label string 'Context window' Name of the meter
variant 'compact' | 'bar' 'compact' Figma: Style. compact (default) — a ring and percentage for a prompt toolbar; details open on click. bar — label, bar and numbers inline, for side panels and settings.
warnAt number 80 Percentage at which the meter turns warning; error from 95%
locale string — BCP 47 locale for numbers
placement 'up' | 'down' 'up' Which way the compact details open; up suits a prompt input at the bottom of the screen
defaultOpen boolean — Start with the compact details open (docs and tests)
className string — Extra class on the root element (layout only — never restyle colours or sizes).

Accepts only the props above.

ContextUsagePart:

Field Type Description
label string “Input”, “Output”, “Cached”, “Tools” …
tokens number Tokens in this part