Loading…

AI Token Usage

A gauge showing how much of the context window a conversation has used.

AI
1 file
No extra npm packages
Accessibility notes

Playground

Installation

The CLI installs popover as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add ai-token-usage

No npm packages are needed beyond what Dowel already requires.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { TokenUsage } from "@/components/ui/ai-token-usage";

Examples

Every example the tests run, live and operable, side by side.

Default
Thresholds
Custom Format
Inline Count
Ring
Ring With Breakdown
Compact
Danger Threshold

API

Generated from the component's own types, so a prop cannot appear here without existing.

<TokenUsage>

Prop	Type	Default
`limit` (required) The context window.	`number`	—
`used` (required) Tokens used so far.	`number`	—
`breakdown` What is filling the window. Listed under the bar; in the ring variant, in a popover from the gauge.	`TokenUsageBreakdownItem[]`	—
`dangerAt` Fraction past which the gauge reads as critical, before the limit itself.	`number`	—
`format` Formats the numbers. Defaults to the runtime locale's grouping.	`(value: number) => string`	—
`label`	`string`	`"Context used"`
`notation` Number style when `format` is not given. `compact` writes 48000 as "48K". Defaults to `standard`, or to `compact` in the ring variant.	`TokenNotation`	—
`variant` `bar` is a labelled bar. `ring` is a compact inline gauge for toolbars: it changes hue as it fills, never size, since growth would read as health.	`"bar" \| "ring"`	`"bar"`
`warnAt` Fraction of the limit past which the gauge warns.	`number`	`0.85`

Plus every attribute of <div>.

<TokenUsageBreakdown>

Prop	Type	Default
`items` (required)	`TokenUsageBreakdownItem[]`	—
`format`	`(value: number) => string`	`defaultFormat`

Plus every attribute of <dl>.

<TokenCount>

Prop	Type	Default
`value` (required)	`number`	—
`format`	`(value: number) => string`	—
`label`	`string`	`"tokens"`
`notation` Number style when `format` is not given.	`TokenNotation`	`"standard"`

Plus every attribute of <span>.

Accessibility

The numbers are the content and the bar only summarises them, so the bar is aria-hidden rather than a second progressbar to read past. Counts are formatted for the locale. Warning and over-limit states change the wording's colour but never remove the figures. The ring variant abbreviates its visible figures, so it carries a visually hidden sentence with the full numbers and percent. Its breakdown trigger is a real, never-disabled button: click, Enter or Space open it and Escape closes it; a mouse hover also opens it without moving focus, and focus alone never does.

Quality

Measured from the source and its tests at build time.

All scores

9/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — fails
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Used in

Whole screens assembled from this component. Installing one brings this and everything else it needs with it.

Prop

Type

Default

limit

The context window.

number

—

used

Tokens used so far.

number

—

breakdown

What is filling the window. Listed under the bar; in the ring variant, in a popover from the gauge.

TokenUsageBreakdownItem[]

—

dangerAt

Fraction past which the gauge reads as critical, before the limit itself.

number

—

format

Formats the numbers. Defaults to the runtime locale's grouping.

(value: number) => string

—

label

string

"Context used"

notation

Number style when format is not given. compact writes 48000 as "48K". Defaults to standard, or to compact in the ring variant.

TokenNotation

—

variant

bar is a labelled bar. ring is a compact inline gauge for toolbars: it changes hue as it fills, never size, since growth would read as health.

"bar" | "ring"

"bar"

warnAt

Fraction of the limit past which the gauge warns.

number

0.85

Prop

Type

Default

items

TokenUsageBreakdownItem[]

—

format

(value: number) => string

defaultFormat

Prop

Type

Default

value

number

—

format

(value: number) => string

—

label

string

"tokens"

notation

Number style when format is not given.

TokenNotation

"standard"