Context display

npx shadcn@latest add "@assistant-ui/context-display"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-context-display"

Context display turns a model's token usage into a small gauge with three faces: a ring, a bar, or a plain text fraction, each opening the same tooltip breakdown on hover. With a runtime it reads usage off the latest assistant message; standalone you hand it a usage object yourself.

Getting started

import { streamText, convertToModelMessages } from "ai";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: getModel(),
    messages: await convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === "finish") return { usage: part.totalUsage };
      if (part.type === "finish-step")
        return { modelId: part.response.modelId };
      return undefined;
    },
  });
}

import { ContextDisplay } from "@/components/assistant-ui/elements/context-display.aui";

function ThreadFooter() {
  return (
    <div className="flex items-center justify-end px-3 py-1.5">
      <ContextDisplay.Bar modelContextWindow={128000} />
    </div>
  );
}

import { ContextDisplayBar } from "@/components/assistant-ui/elements/context-display";

export function UsageBadge() {
  return (
    <ContextDisplayBar
      modelContextWindow={128000}
      usage={{ totalTokens: 42000, inputTokens: 38000, outputTokens: 4000 }}
    />
  );
}

Anatomy

Every preset is the same shape: a trigger wrapped in a shared tooltip.

<button data-slot="context-display-trigger">
  {/* Ring: SVG donut + percent. Bar: fill bar + token count. Text: "12k / 128k" */}
</button>
<div data-slot="context-display-popover">
  <div>Context usage   <span>{/* used of total */}</span></div>
  <div>{/* progress bar, min-width 1px once usage is nonzero */}</div>
  <div>Input           <span>{/* only when > 0 */}</span></div>
  <div>Cached input    <span>{/* only when > 0 */}</span></div>
  <div>Output          <span>{/* only when > 0 */}</span></div>
  <div>Reasoning       <span>{/* only when > 0 */}</span></div>
</div>

The breakdown only lists segments with a nonzero token count, so a usage object that carries only totalTokens shows the summary line with no rows underneath it. Percent is clamped to 100 even when usage exceeds the context window. The running total is sticky rather than reactive to every update: it only moves when the incoming total is itself nonzero, or when resetKey changes. A momentary usage of undefined (or zero) between turns does not flash the number back down, but a changed resetKey snaps it immediately to whatever the new usage reports.

Examples

Three presets

Each preset wraps Root, Trigger, and Content with one specific visual. Ring draws an SVG donut with a percent label, Bar draws a fill bar with a token count beside it, and Text prints a plain fraction with no severity color at all. Ring and Bar both shift color at the same two thresholds: the default tone below 65% usage, amber from 65% to 85%, and red above 85%.

<ContextDisplay.Ring modelContextWindow={128000} />
<ContextDisplay.Bar modelContextWindow={128000} />
<ContextDisplay.Text modelContextWindow={128000} />

<ContextDisplay.Ring modelContextWindow={128000} usage={usage} />
<ContextDisplay.Bar modelContextWindow={128000} usage={usage} />
<ContextDisplay.Text modelContextWindow={128000} usage={usage} />

Compose your own visual

Root, Trigger, and Content are exported on their own for a fully custom trigger visual. Root computes the shared percent and segment breakdown for Content's tooltip, but that computation is internal to the module. A custom child passed to Trigger renders whatever you put there, so pair it with your own modelContextWindow/usage math rather than expecting it to read Root's numbers.

<ContextDisplay.Root modelContextWindow={128000}>
  <ContextDisplay.Trigger aria-label="Context usage">
    <MyCustomGauge />
  </ContextDisplay.Trigger>
  <ContextDisplay.Content side="top" />
</ContextDisplay.Root>

Restyle the trigger

Both lanes take className on the trigger, and side controls which edge the popover opens toward.

<ContextDisplay.Bar className="px-1" side="bottom" modelContextWindow={128000} />

API reference