Context

kai-context

A compact token-usage meter with a hover-card breakdown — shows used vs. available context at a glance, with input, output, reasoning, and cache line items revealed on hover.

• Shadow DOM
• 1 event
• Configurable thresholds
• Hover-card breakdown
• Estimated cost display

Preview

When to use

Place <kai-context> in a chat header or toolbar alongside a model switcher. The meter is inline-block and compact — it fits next to other controls without its own row. Wire kai-threshold-change to act when usage reaches 'warn' or 'danger' (e.g. prompt the user to start a new conversation).

Usage

Set context in JavaScript with a usage object:

import '@kitn.ai/ui/elements';

await customElements.whenDefined('kai-context');

const el = document.querySelector('kai-context');
el.context = {
  usedTokens: 48200,
  maxTokens: 200000,
  inputTokens: 31000,
  outputTokens: 17200,
  reasoningTokens: 4200, // optional — shown when present
  cacheTokens: 8000,     // optional — shown when present
  estimatedCost: 0.42,   // optional — shown in the footer
};

• context — the element renders nothing until data arrives, so it’s safe to place unconditionally in the header.
• warnThreshold / dangerThreshold are fractional (0–1) number properties, defaulting to 0.7 and 0.9. Assign directly: el.warnThreshold = 0.5.

Examples

Default

Meter at ~24% usage with a full breakdown. Hover to reveal the popover.

Code

Warning Threshold

At 75% the meter turns yellow — above the default warnThreshold of 0.7.

Code

Danger Threshold

At 92% the meter turns red — above the default dangerThreshold of 0.9.

Code

Custom Thresholds

warnThreshold: 0.5, dangerThreshold: 0.75 — the meter warns earlier.

Code

Styling

The meter inside the hover-card breakdown exposes two ::parts. Both are in the DOM only while the card is open.

Part	Purpose	Example
track	The usage meter track inside the hover-card breakdown. Carries `role="progressbar"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside.	kai-context::part(track) { height: 0.5rem }
fill	The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal.	kai-context::part(fill) { background: var(--color-tool-blue) }

Props

Property	Type	Default	Notes
theme	"light" | "dark" | "auto"	'auto'	Color mode (`auto` follows prefers-color-scheme).
context	KaiContextUsage	—	Token-usage data. Set as a JS property.
warnThreshold	number	—	Fraction (0–1) above which the meter turns yellow. Defaults to `0.7` (70%).
dangerThreshold	number	—	Fraction (0–1) above which the meter turns red. Defaults to `0.9` (90%).

Events

Event	Detail	Notes
kai-threshold-change	{ … }	Fires when the computed severity level changes (ok → warn → danger or back). `detail.level` is `'ok'`, `'warn'`, or `'danger'`.

Composed from

This element wraps these SolidJS components — reach for them directly when you need finer control than the props expose.

ContextContextTriggerContextContentContextContentHeaderContextContentBodyContextContentFooterContextInputUsageContextOutputUsageContextReasoningUsageContextCacheUsage

---

Need a hand? Report a bug Ask for help