ai context meter.md
AI Context Meter
How full the context window is, as a ring in the prompt footer that opens a breakdown by source and compacts when it fills.
Source: https://kokonutui.com/docs/ai/ai-context-meter
Installation
npx shadcn@latest add @kokonutui/ai-context-meter
Props
| Prop | Type | Default | Description |
|---|---|---|---|
segments? |
ContextSegment[] |
What fills the context window, in the order to draw it. When omitted, a demo conversation grows on its own. | |
limit? |
number |
200_000 |
The model's context window, in tokens. |
compactAt? |
number |
0.8 |
Share of the window at which the conversation compacts, 0 to 1. |
onCompact? |
() => void |
Shows a Compact button in the panel. The demo compacts by itself. | |
model? |
string |
"Claude Opus" |
Shown beside the meter, like the footer of a prompt box. |
defaultOpen? |
boolean |
false |
|
className? |
string |
Extra classes for the root element. |
ContextSegment
| Field | Type | Description |
|---|---|---|
id |
string |
|
label |
string |
|
tokens |
number |
|
color? |
string |
A Tailwind background class for the segment, such as bg-sky-500. |
Source
"use client";
/**
* @author: @kokonutui
* @description: AI Context Meter
* @version: 1.0.0
* @date: 2026-10-15
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import { AnimatePresence, MotionConfig, motion } from "motion/react";
import { useCallback, useEffect, useId, useRef, useState } from "react";
import { cn } from "@/lib/utils";
export interface ContextSegment {
id: string;
label: string;
tokens: number;
/** A Tailwind background class for the segment, such as `bg-sky-500`. */
color?: string;
}
interface AIContextMeterProps {
/**
* What fills the context window, in the order to draw it. When omitted, a
* demo conversation grows on its own.
*/
segments?: ContextSegment[];
/** The model's context window, in tokens. */
limit?: number;
/** Share of the window at which the conversation compacts, 0 to 1. */
compactAt?: number;
/** Shows a Compact button in the panel. The demo compacts by itself. */
onCompact?: () => void;
/** Shown beside the meter, like the footer of a prompt box. */
model?: string;
defaultOpen?: boolean;
className?: string;
}
const DEMO_BASE: ContextSegment[] = [
{ id: "system", label: "System prompt", tokens: 3100 },
{ id: "tools", label: "Tools", tokens: 14_200 },
{ id: "files", label: "Files", tokens: 38_600 },
];
function useDemoContext(
enabled: boolean,
limit: number,
compactAt: number,
rootRef: React.RefObject<HTMLElement | null>
) {
const [messages, setMessages] = useState(61_000);
const [summary, setSummary] = useState(0);
const [visible, setVisible] = useState(true);
const turnRef = useRef(0);
useEffect(() => {
const element = rootRef.current;
if (!(enabled && element)) {
return;
}
const observer = new IntersectionObserver(([entry]) =>
setVisible(entry.isIntersecting)
);
observer.observe(element);
return () => observer.disconnect();
}, [enabled, rootRef]);
const base = DEMO_BASE.reduce((sum, segment) => sum + segment.tokens, 0);
const total = base + summary + messages;
const full = total >= limit * compactAt;
useEffect(() => {
if (!(enabled && visible) || full) {
return;
}
const id = setInterval(() => {
turnRef.current += 1;
const size =
turnRef.current % 3 === 0 ? 9400 : 2600 + (turnRef.current % 4) * 900;
setMessages((value) => value + size);
}, 1100);
return () => clearInterval(id);
}, [enabled, visible, full]);
const segments: ContextSegment[] = [
...DEMO_BASE,
{ id: "summary", label: "Summary", tokens: summary },
{ id: "messages", label: "Messages", tokens: messages },
];
const compact = useCallback(() => {
setSummary(5800);
setMessages(0);
}, []);
useEffect(() => {
if (!(enabled && visible && full)) {
return;
}
const id = setTimeout(compact, 1400);
return () => clearTimeout(id);
}, [enabled, visible, full, compact]);
return { segments, compact };
}
const DEMO_COLORS: Record<string, string> = {
system: "bg-zinc-300 dark:bg-zinc-600",
tools: "bg-zinc-400 dark:bg-zinc-500",
files: "bg-zinc-600 dark:bg-zinc-400",
summary: "bg-sky-300 dark:bg-sky-700",
messages: "bg-sky-500 dark:bg-sky-400",
};
const formatTokens = (tokens: number) =>
tokens >= 1000
? `${(tokens / 1000).toFixed(tokens >= 10_000 ? 0 : 1)}k`
: `${Math.round(tokens)}`;
function levelColor(share: number, compactAt: number) {
if (share >= compactAt + (1 - compactAt) / 2) {
return "text-red-600 dark:text-red-400";
}
if (share >= compactAt - 0.1) {
return "text-orange-700 dark:text-orange-400";
}
return "text-zinc-900 dark:text-zinc-100";
}
function BreakDown({
segments,
limit,
compactAt,
colors,
onCompact,
}: {
segments: ContextSegment[];
limit: number;
compactAt: number;
colors: string[];
onCompact?: () => void;
}) {
const [active, setActive] = useState<string | null>(null);
const used = segments.reduce((sum, segment) => sum + segment.tokens, 0);
const free = Math.max(0, limit - used);
return (
<div className="w-72 p-3">
<div className="mb-2.5 flex items-baseline justify-between">
<p className="font-medium text-sm text-zinc-900 dark:text-zinc-100">
Context
</p>
<p className="text-xs text-zinc-500 tabular-nums dark:text-zinc-400">
{formatTokens(used)} of {formatTokens(limit)}
</p>
</div>
<div className="relative" onPointerLeave={() => setActive(null)}>
<div className="flex h-2 overflow-hidden rounded-full bg-zinc-100 dark:bg-white/10">
{segments.map((segment, index) => (
<span
className={cn(
"h-full transition-[width,opacity] duration-500 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none",
index > 0 && segment.tokens > 0 && "ml-px",
colors[index],
active && active !== segment.id && "opacity-30"
)}
key={segment.id}
onPointerEnter={() => setActive(segment.id)}
style={{ width: `${(segment.tokens / limit) * 100}%` }}
/>
))}
</div>
<span
aria-hidden="true"
className="absolute -top-1 -bottom-1 w-px bg-zinc-400 dark:bg-zinc-500"
style={{ left: `${compactAt * 100}%` }}
/>
</div>
<p className="mt-1.5 text-right text-[11px] text-zinc-400 dark:text-zinc-500">
Compacts at {Math.round(compactAt * 100)}%
</p>
<ul className="mt-2 space-y-0.5">
{segments.map((segment, index) =>
segment.tokens > 0 ? (
<li
className={cn(
"flex items-center gap-2 rounded-md px-1.5 py-1 text-xs transition-colors duration-150",
active === segment.id && "bg-zinc-100 dark:bg-white/5"
)}
key={segment.id}
onPointerEnter={() => setActive(segment.id)}
onPointerLeave={() => setActive(null)}
>
<span className={cn("size-2 rounded-[3px]", colors[index])} />
<span className="text-zinc-700 dark:text-zinc-300">
{segment.label}
</span>
<span className="ml-auto text-zinc-500 tabular-nums dark:text-zinc-400">
{formatTokens(segment.tokens)}
</span>
<span className="w-9 text-right text-zinc-400 tabular-nums dark:text-zinc-500">
{((segment.tokens / limit) * 100).toFixed(1)}%
</span>
</li>
) : null
)}
<li className="flex items-center gap-2 px-1.5 py-1 text-xs">
<span className="size-2 rounded-[3px] ring-1 ring-zinc-300 ring-inset dark:ring-zinc-600" />
<span className="text-zinc-500 dark:text-zinc-400">Free</span>
<span className="ml-auto text-zinc-500 tabular-nums dark:text-zinc-400">
{formatTokens(free)}
</span>
<span className="w-9 text-right text-zinc-400 tabular-nums dark:text-zinc-500">
{((free / limit) * 100).toFixed(1)}%
</span>
</li>
</ul>
{onCompact && (
<div className="mt-3 flex items-center justify-between border-zinc-100 border-t pt-3 dark:border-white/10">
<p className="text-xs text-zinc-500 dark:text-zinc-400">
Summarize older turns
</p>
<button
className="h-7 rounded-md bg-zinc-900 px-2.5 font-medium text-white text-xs outline-hidden transition-colors duration-150 hover:bg-zinc-700 focus-visible:ring-2 focus-visible:ring-zinc-400/60 disabled:bg-zinc-200 dark:bg-white dark:text-zinc-900 dark:disabled:bg-white/10 dark:disabled:text-zinc-500 dark:hover:bg-zinc-200"
disabled={used / limit < 0.4}
onClick={onCompact}
type="button"
>
Compact now
</button>
</div>
)}
</div>
);
}
export default function AIContextMeter({
segments: segmentsProp,
limit = 200_000,
compactAt = 0.8,
onCompact,
model = "Claude Opus",
defaultOpen = false,
className,
}: AIContextMeterProps) {
const rootRef = useRef<HTMLDivElement>(null);
const demo = useDemoContext(
segmentsProp === undefined,
limit,
compactAt,
rootRef
);
const isDemo = segmentsProp === undefined;
const segments = segmentsProp ?? demo.segments;
const colors = segments.map(
(segment, index) =>
segment.color ??
(isDemo
? DEMO_COLORS[segment.id]
: FALLBACK_COLORS[
Math.max(0, FALLBACK_COLORS.length - segments.length + index)
])
);
const used = segments.reduce((sum, segment) => sum + segment.tokens, 0);
const share = used / limit;
const [open, setOpen] = useState(defaultOpen);
const panelId = useId();
const triggerRef = useRef<HTMLButtonElement>(null);
useEffect(() => {
if (!open) {
return;
}
const onPointer = (event: PointerEvent) => {
if (!rootRef.current?.contains(event.target as Node)) {
setOpen(false);
}
};
const onKey = (event: KeyboardEvent) => {
if (event.key === "Escape") {
setOpen(false);
}
};
document.addEventListener("pointerdown", onPointer);
document.addEventListener("keydown", onKey);
return () => {
document.removeEventListener("pointerdown", onPointer);
document.removeEventListener("keydown", onKey);
};
}, [open]);
const handleCompact = isDemo ? demo.compact : onCompact;
return (
<MotionConfig reducedMotion="user">
<div className={cn("w-full max-w-sm", className)} ref={rootRef}>
<div className="relative flex h-11 items-center justify-between rounded-xl bg-black/5 pr-1.5 pl-3 dark:bg-white/5">
<span className="text-xs text-zinc-600 dark:text-zinc-300">
{model}
</span>
<button
aria-controls={panelId}
aria-expanded={open}
aria-label={`Context ${Math.round(share * 100)}% full. Show breakdown`}
className={cn(
"flex h-8 items-center gap-1.5 rounded-lg px-2 text-xs outline-hidden transition-colors duration-150 hover:bg-black/5 focus-visible:ring-2 focus-visible:ring-zinc-400/50 dark:hover:bg-white/10",
open && "bg-black/5 dark:bg-white/10",
levelColor(share, compactAt)
)}
onClick={() => setOpen((value) => !value)}
ref={triggerRef}
type="button"
>
<Ring share={share} />
<span className="font-medium tabular-nums">
{Math.round(share * 100)}%
</span>
</button>
<AnimatePresence>
{open && (
<motion.div
animate={{ opacity: 1, scale: 1, y: 0 }}
className="absolute right-0 bottom-full z-10 mb-2 origin-bottom-right rounded-xl bg-white shadow-[0_8px_24px_-8px_rgb(0_0_0/0.18)] ring-1 ring-black/10 dark:bg-zinc-900 dark:ring-white/10"
exit={{ opacity: 0, scale: 0.97, y: 4 }}
id={panelId}
initial={{ opacity: 0, scale: 0.97, y: 4 }}
transition={{ duration: 0.16, ease: EASE_OUT }}
>
<BreakDown
colors={colors}
compactAt={compactAt}
limit={limit}
onCompact={handleCompact}
segments={segments}
/>
</motion.div>
)}
</AnimatePresence>
</div>
</div>
</MotionConfig>
);
}