# Context Meter (/docs/agent-ui/components/context-meter)

Use a context meter beside the composer, so a person can see when a conversation is about to run out of room. It's a small ring and a percentage, and its details list the tokens by kind and what the conversation has cost.

<Example caption="Rest the pointer on the meter, or press it, to show its details. Press Escape to close them.">
<g />

```tsx
import { ContextMeter } from "@/components/ui/context-meter";

export default function ContextMeterExample() {
  return (
    <ContextMeter
      used={57_600}
      total={128_000}
      usage={{ input: 40_000, output: 12_000, reasoning: 5_600, cached: 20_000 }}
      cost={0.42}
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/context-meter
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/context-meter-web
```

## Composition [#composition]

```text
ContextMeter
├── ContextMeterTrigger
│   └── ContextMeterValue
└── ContextMeterContent
    ├── ContextMeterTitle
    ├── ContextMeterDescription
    └── ContextMeterRows
```

`ContextMeter` renders these parts when you pass no children: a group named by its `label`. `ContextMeterTrigger` is a button that opens the details, and `ContextMeterValue` holds UI SDK's Meter, drawn as a ring with the percentage beside it. `ContextMeterContent` is the popover with the details: `ContextMeterTitle` names it, `ContextMeterDescription` reads the tokens used, and `ContextMeterRows` lists each count and the cost.

## Usage [#usage]

### The Value [#the-value]

Pass `used` and `total` in tokens. The ring fills to how much of the window is used and the percentage sits beside it, in tabular numbers at a fixed width, so a new value never moves what's next to the meter. Screen readers hear the button as "57,600 of 128,000 tokens, 45%". Numbers follow the page's `lang`, or the browser's language without one; pass `locale` to choose another.

### Levels [#levels]

From 80%, as the percentage reads, the ring turns to the warning color with an exclamation mark inside it, and from 95% to the danger color with its middle filled. The root's `data-level` reads `normal`, `high` or `full` for your own styles.

### Details [#details]

Pass `usage` with any of `input`, `output`, `reasoning` and `cached`, and `cost` with its `currency` (`"USD"` unless you say), to list them in the details. Only what you pass shows, `0` included, in that order. Without either, the details show the title and the tokens used.

```tsx
<ContextMeter used={57_600} total={128_000} usage={{ input: 40_000, cached: 20_000 }} cost={0.42} currency="EUR" />
```

### Opening [#opening]

The details open when the pointer rests on the meter for 600 ms, when keyboard focus rests on it as long, and when it's pressed, by pointer, Enter or Space. They close on Escape, a press outside or focus leaving the meter, and a press on the meter closes them unless resting the pointer opened them. Details the pointer opened also close 300 ms after it leaves both the meter and the details. Opening them by pointer or keyboard leaves focus on the meter, since they hold nothing to press.

Pass `open` and `onOpenChange` to control them, or `defaultOpen` to start with them open. `onOpenChange` gets UI SDK Popover's reason, like `trigger-hover`, `trigger-press` or `escape-key`, or `trigger-focus` when keyboard focus opened them.

### Motion [#motion]

The ring sweeps to a new value, and the details rise and fade in. Under `prefers-reduced-motion`, or with `motion="reduced"`, the ring moves at once and the details only fade, over 120 ms, and with `motion="none"` nothing animates.

## API Reference [#api-reference]

### ContextMeterOptions

| Prop            | Type                                                                                           | Description                                                                                                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `used?`         | `number \| undefined`                                                                          | Tokens the conversation takes up in the context window. Default: `0`                                                                                                                             |
| `total?`        | `number \| undefined`                                                                          | Tokens the context window holds. Default: `0`                                                                                                                                                    |
| `usage?`        | `TokenUsage \| undefined`                                                                      | Token counts the details list: input, output, reasoning and cached. Only the counts you supply show.                                                                                             |
| `cost?`         | `number \| undefined`                                                                          | What the conversation has cost so far, in `currency`. The details show it when supplied.                                                                                                         |
| `currency?`     | `string \| undefined`                                                                          | The ISO 4217 code `cost` is in, like `"EUR"`. Default: `"USD"`                                                                                                                                   |
| `locale?`       | `string \| undefined`                                                                          | The locale numbers are formatted in, like `"de-DE"`. Defaults to the page's `lang`, or the browser's language without one, once the meter is in the page; server markup uses English until then. |
| `label?`        | `string \| undefined`                                                                          | Names the meter. Default: `"Context"`                                                                                                                                                            |
| `open?`         | `boolean \| undefined`                                                                         | Whether the details are open. Passing it controls them: change it in `onOpenChange`.                                                                                                             |
| `defaultOpen?`  | `boolean \| undefined`                                                                         | Whether the details are open at first, when `open` isn't passed. Default: `false`                                                                                                                |
| `onOpenChange?` | `((open: boolean, details: ChangeDetails<ContextMeterOpenChangeReason>) => void) \| undefined` | Called when the details open or close, with what caused it.                                                                                                                                      |
| `motion?`       | `"auto" \| "none" \| "reduced"`                                                                | How the ring fills and the details open: at full motion the ring sweeps and the details rise in; reduced motion only fades. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`         |

### Agent [#agent]

An agent connected with `createAgent` finds the meter by its label and reads whether its details are open. `open` is offered while they're closed and `close` while they're open; both report `details.source` as `"agent"` to `onOpenChange`. Like any component with a button, it also has UI SDK's generic `press`.

### ContextMeterAgentActions

| Prop    | Type                           | Description                                                                                    |
| ------- | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `open`  | `(() => boolean) \| undefined` | Opens the details. Offered only while they're closed. Returns whether the change was accepted. |
| `close` | `(() => boolean) \| undefined` | Closes the details. Offered only while they're open. Returns whether the change was accepted.  |

<Caption>
Runs in React and Web Components. On `<kind-context-meter>`, props are kebab-case attributes, `usage` is a property, and `open` is a property too; `onOpenChange` is the `openchange` event. The element fills in its parts when it has no children.
</Caption>