Context Window / Usage Meter

How much of the model's context window is used, and by what.

Import

import { ContextUsage } from '@marbleui/ui'

Props

<ContextUsage>

Prop	Type	Default	Description
limit *required	`number`	`—`
parts *required	`ContextPart[]`	`—`
className	`string`	`—`
variant	`'bar' \| 'ring'`	`'ring'`	"ring": compact trigger with a popover breakdown. "bar": inline segmented bar.
warnAt	`number`	`0.8`	Share of the limit (0–1) above which the warning shows and the ring turns amber. Default 0.8.
warning	`ReactNode`	`'Close to the limit: older messages will be summarized soon.'`	Shown past `warnAt`. Default: "Close to the limit: older messages will be summarized soon."

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitives: React Aria DialogTrigger · React Aria Dialog · React Aria Button. Follow the primitive's docs for the full keyboard map.

Usage notes

How much of the model’s context window is used, and by what. The default is a compact ring button that opens a breakdown popover; variant="bar" shows the breakdown inline.

<ContextUsage
  limit={200_000}
  parts={[{ label: 'System prompt', tokens: 4200 }, { label: 'Tools', tokens: 11800 }, { label: 'Conversation', tokens: 96400 }]}
/>

Token counts come from your model or tokenizer; the component only sums and abbreviates them (“11.8K”).
Parts take --chart-1…8 in order, and a ninth part starts again at --chart-1. Keep labels unique (they’re the keys). Over the limit the bar’s segments are scaled to fit and the label caps at 100%.
Above warnAt (default 0.8) the ring turns to the warning color and the breakdown shows warning (default: older messages “will be summarized soon”). Pass your own text to match what your app does, or warning={null} to hide it.
The ring button is labelled “Context N% used”, and the breakdown lists every part as text.

Example source · show

import { ContextUsage } from './context-usage'

const parts = [
  { label: 'System prompt', tokens: 4200 },
  { label: 'Tools', tokens: 11800 },
  { label: 'Files', tokens: 52000 },
  { label: 'Conversation', tokens: 96400 },
]

export const styles = {
  Ring: () => <div className="flex h-64 items-end"><ContextUsage parts={parts} limit={200_000} /></div>,
  Bar: () => <ContextUsage parts={parts} limit={200_000} variant="bar" />,
}

Source: packages/ui/src/context-usage/context-usage.tsx

Catalog

Category: ai-agents
Priority: Pro
Primitive: composed
React Aria: Meter
Base UI: Meter