Context usage

A native disclosure of context occupancy, token categories and estimated costs from application-supplied rates or model catalogs.

Preview

Context usage · 10%

Example model

12,400 of 128,000 tokens10%

Input tokens: 10,800
Output tokens: 1,600
Reasoning tokens: 400
Cached input tokens: 4,200

In action

Read the supplied context budget

Context usage · 10%

Example model

12,400 of 128,000 tokens10%

Input tokens: 10,800
Output tokens: 1,600
Reasoning tokens: 400
Cached input tokens: 4,200

Token usage and limits come from the application. Optional prices are supplied per million tokens; cached input and reasoning remain subsets of input and output. Unknown counts and rates stay unavailable.

When to use

Use it for

Supply usedTokens and maxTokens for context occupancy; usage supplies separate input, output, reasoning and cached-input counts.
pricing accepts inputPerMillion, outputPerMillion, reasoningPerMillion, cacheReadPerMillion and optional currency. No model catalog or prices are fetched.
Pass modelId and a supplied Tokenlens or models.dev catalog to resolve a model name, context limit, and rates. Explicit model, maxTokens, and pricing replace their resolved counterparts.
resolveContextPricing exposes the same lookup for application composition. Qualified provider/model ids select provider pricing; a providerless id must match exactly one model.
Catalog context tiers require the actual input token count through usage.inputTokens, or inputTokens in resolver options. Unknown, ambiguous, or invalid metadata remains unavailable.
Cached input is a subset of input; reasoning is a subset of output. Separate rates replace the parent rate for those subsets rather than adding duplicate charges.
Missing or invalid data displays Unavailable. Costs are estimates from the supplied rates, not provider billing totals.
Use open/onToggle for a controlled native disclosure or defaultOpen for the initial state. CSS-only markup shows supplied values.

Avoid

Treating missing token counts or unknown pricing as zero.
Displaying rates without verifying them in the application that supplies them.

Install

React package

npm install @noorddev/vlak-react

Load the stylesheet once at your app root, then import the components you use.

import "@noorddev/vlak-react/css";
import { ContextUsage, type ContextPricingCatalog } from "@noorddev/vlak-react";

Per-component imports are available at @noorddev/vlak-react/components/context-usage.

Copy the source

npx @noorddev/vlak-cli add context-usage

Adds the component and its dependencies to components/vlak/. Follow the StyleX setup to compile the source in your application.

shadcn registry

npx shadcn add https://vlak.dev/r/context-usage.json

Installs the same source through the shadcn CLI.

React

import { ContextUsage, type ContextPricingCatalog } from "@noorddev/vlak-react";

export function ContextExample({ modelId, catalog }: {
  modelId: string;
  catalog: ContextPricingCatalog;
}) {
  return <ContextUsage
    modelId={modelId}
    catalog={catalog}
    usedTokens={1500}
    usage={{ inputTokens: 1000, outputTokens: 500, cachedInputTokens: 200, reasoningTokens: 100 }}
  />;
}

See the integration example to compose these components with your application's model and data.

Props

ContextUsage

Context occupancy and caller-supplied token usage/pricing. No model catalog or prices are fetched.

Prop	Type	Default	Description
`usedTokens`required	`number`
`maxTokens`	`number`
`usage`	`TokenUsage`
`pricing`	`TokenPricing`
`modelId`	`string`		Optional metadata from an application-owned Tokenlens/models.dev catalog. Explicit limits and rates take precedence.
`catalog`	`Readonly<Record<string, { id?: string; models: Readonly<Record<string, ContextModelPricing>>; }>>`
`model`	`string`
`label`	`string`	`"Context usage"`
`defaultOpen`	`boolean`	`false`

Also accepts Omit<DetailsHTMLAttributes<HTMLDetailsElement>, "title">.

The ref reaches HTMLDetailsElement.

resolveContextPricing (function)

Resolve cached catalog metadata without fetching, timers, or a bundled pricing snapshot. Qualified provider/model ids select the provider's prices; providerless ids must be unique. Catalogs may be obtained with Tokenlens or models.dev in application/server code.

Keyboard

Keys	Does
`Tab`	Focuses the native disclosure summary
`Enter, Space`	Opens or closes usage details

Accessibility

The summary exposes current occupancy in text. The shared Progress names the token range and clamps its visual extent.
Unknown limits omit the meter; usage above the supplied limit retains the real count and an explanation.
Native details attributes and its ref are forwarded.

Markup

The same styles are available as CSS. Native HTML provides the static presentation; React or application code supplies state updates and actions.

npm install @noorddev/vlak

import "@noorddev/vlak/css";

<details class="rs-context-usage rs-disclosure"><summary class="rs-disclosure-summary">Context usage · 25%</summary><div class="rs-context-usage-body"><p class="rs-context-usage-metadata">512 of 2,048 tokens</p></div></details>

Classes

.rs-context-usage.rs-context-usage-body.rs-context-usage-metadata.rs-context-usage-list.rs-context-usage-row.rs-context-usage-value

Depends on

Collapsible Progress

Use elsewhere

Markdown reference Registry JSON Source AI integration guide