# Context Meter

How full the model's context window is: a ring for the prompt toolbar or a bar with a breakdown.

- Category: AI & Agents
- Page: https://wunderui.com/components/context-meter
- Tier: Core and Pro

## Install

Context Meter ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ContextMeter } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ContextMeter } from "@wunderui/react"

const parts = [
  { label: "System", tokens: 6_200 },
  { label: "Files", tokens: 41_800 },
  { label: "Conversation", tokens: 26_000 },
]

export function Window() {
  return <ContextMeter variant="bar" used={74_000} limit={200_000} breakdown={parts} />
}
```

Expected result: You see Context window and 74k of 200k tokens, a bar in three segments with free space at the end, and a legend with each part's tokens. From 80% the figures turn amber.

## When to use

### Use Context Meter for

- How full the context window is, as a ring in the toolbar of a prompt
- What fills the window (system, files, conversation, tools) as a bar with a legend
- A warning before the window is full, with the next step beside it

### Use something else

- [Usage Meter](https://wunderui.com/components/usage-meter) for one limit of a plan as a row, such as tokens per day
- [Progress](https://wunderui.com/components/progress) for how far a task has come, not how full a window is

## Keyboard

The bar is not interactive. The ring is interactive only with a breakdown, when it becomes a native button that opens a tooltip.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the ring and away from it. Focus opens the tooltip with the breakdown. |
| `Esc` | Closes the tooltip. Focus stays on the ring. |

Without a breakdown the ring is plain text and not a tab stop.

## Behavior

How the meter turns two numbers and a list of parts into a fill and a warning, and how the ring differs from the bar.

- **Fill and warning:** The fill is used divided by the limit, capped at full. From the warning threshold (80% by default) the figures and the ring turn amber and the bar shows its hint.
- **Over the limit:** The text is not capped: 212,000 of 200,000 reads 212k of 200k tokens, while the ring is a full circle. Treat it as a bug in your count, not a normal state.
- **Segments:** Each part is a segment as wide as its share of the limit, in the order you pass them, with free space at the end. Colours cycle through four; a background class on a part overrides its colour.
- **Colour at the warning:** At the warning, segments keep their colours and only the figures, ring and hint turn amber. Without a breakdown the bar is one fill that does turn amber.
- **Hint:** In the bar, the warning line appears from the threshold, by default Nearly full, older messages get summarised next. Pass your own text, or null to hide it.
- **Number format:** Numbers are English and short from 1,000: 98.4k, 172k, 1.25M. The figures use the short form only, so show the exact count in your own text where it matters.
- **Meter semantics:** The bar is a meter from 0 to the limit, named by the label, with the summary as its value text. The ring is plain text, or with a breakdown a button named Context window: 172k of 200k tokens.
- **Live updates:** Pass a new used value and the figures, segments and warning change at once. Nothing is announced automatically, so say the change in a status line next to the meter.
- **Motion:** The bar does not move. The ring arc eases over the ambient duration with the entrance curve, using stroke-dasharray instead of transform, a known gap shared with Usage Meter.
- **Reduced motion:** With reduced motion the arc jumps to its new length. The figures and colours stay the same.

## Anatomy

- `ContextMeter`: The row. It marks itself normal or warning, and a variant picks the bar (shown in the figure) or the ring.
- `Label`: Context window by default. In the bar it names the meter; in the ring it is part of the tooltip and the button name.
- `Summary`: The summary, such as 172k of 200k tokens, which turns amber from the warning threshold. The ring writes 172k / 200k beside the circle instead.
- `Meter bar`: An 8 px track exposed as a meter from 0 to the limit. Each part is a segment with 2 px between them, and the empty end is the free space.
- `Legend`: One entry per part, in order, with a dot in the segment colour, the label and its tokens, such as Files 98.4k. It wraps on a narrow screen.
- `Hint`: The warning line under the legend, shown in the bar from the warning threshold. It says what happens next, and the ring never shows it.
- `Ring`: In the ring variant: a 20 px circle that fills clockwise from the top, with the figures beside it. It turns amber at the warning threshold.
- `Breakdown tooltip`: With a breakdown, the ring and its figures become one button. Hover or focus opens a tooltip with the label, the summary and the legend.

## Best practices

### When to use

- Use ContextMeter for how full the model's context window is: the ring in a prompt toolbar, the bar where the breakdown deserves room. For money use Usage Meter, for plan quotas Usage Meter.

### Do

- Pass a breakdown whose parts add up to the used count. The bar draws the parts and the header writes the total, so mismatched numbers show two different fill levels.
- Order the parts by what stays and what goes: system and files first, the conversation last, free space at the end of the bar.
- Rewrite the warning to say what your product does next, and put the action beside it, such as Summarize and continue.
- Use the ring with a breakdown in a toolbar. It becomes a button, so keyboard and screen reader users can reach the parts.

### Don't

- Don't keep the default warning if nothing summarises. It promises that older messages get summarised next, but the meter only says it.
- Don't count characters as tokens. Use the count your backend reports, or the estimate drifts from the real window.
- Don't use the ring without a breakdown where people need to see what fills the window. Without one it is plain text and takes no focus.

## API reference

### ContextMeter

| Prop | Type | Default | Description |
|---|---|---|---|
| limit* | number |  | The size of the window in tokens. 0 draws an empty meter. |
| used* | number |  | Tokens in the window. It should equal the sum of the parts of `breakdown`. |
| actions | React.ReactNode |  | `bar` only: buttons under the warning, e.g. "Summarise and continue" and "Start a new chat". |
| breakdown | ContextPart[] |  | What fills the window: `{ label, tokens, className? }` per part. `className` is a Tailwind background class for the segment and its dot. In the ring the parts open in a tooltip, in the bar they are segments and a legend. |
| className | string |  | Extra classes for the meter, for example `max-w-sm`. |
| label | string | "Context window" | The name of the meter, `Context window` by default. It is the heading of the bar and part of the ring's tooltip and button name. |
| variant | "ring" \| "bar" | "ring" | `ring` (default) is compact, for a prompt toolbar. `bar` shows the label, the summary, the segments, the legend and the hint. |
| warnAt | number | 0.8 | The share of the window, from 0 to 1, where the meter turns amber. Default `0.8`. |
| warning | React.ReactNode | "Nearly full — older messages get summarised next." | The hint under the bar from `warnAt`. Default `Nearly full — older messages get summarised next.` `null` hides it. The ring does not show it. |

## Examples

### Breakdown: what fills the window

### Warn at: the share of the window where the meter turns amber

### Content: label and compaction hint

### Actions under the warning, ring in a toolbar

## In context

### Filling the window: attach files, then summarize

Attach files and watch the bar fill. A file that does not fit disables its button, and from 160,000 tokens Summarize and continue appears and frees the older messages.

### Prompt toolbar: the ring follows the conversation

The ring sits in the prompt toolbar. Tab to it and the breakdown opens, Escape closes it, and it turns amber at 80% with a status line when the window is nearly full.

### Run panel: state, money, context and quota

The side panel of a running agent. The cost meter is the money of this run, the context meter the window of this conversation, and the usage meter the quota of the plan.

## For AI agents

`get_component("context-meter")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
