Context breakdown
A stacked bar of what fills the context window, so people can see why a chat is getting full.
Loading preview…
Install
- 1
Run this command in your Tailwind CSS project. It adds
components/ai/context-breakdown.tsxand installs its dependencies.$ npx shadcn@latest add https://gradientdeck.com/ai-components/r/context-breakdown.json
Usage & API
Example
import { ContextBreakdown } from "@/components/ai/context-breakdown"
<ContextBreakdown
parts={[]}
contextWindow={1}
/>Props ContextBreakdown
| Prop | Type & description | Required |
|---|---|---|
parts | ContextPart[] | Required |
contextWindow | numberTotal context window, in tokens. | Required |
model | string | Optional |
Dependencies
- React
- Tailwind CSS
- motion
Implementation notes
The stacked row is 36 pixels tall inside a padded track, with 3 pixels between segments. Width is flexGrow set to the token count and flexBasis 0. Free uses a diagonal hatch and no background color. The others use the color on the part, plus a faint top highlight. Leaving the row clears the active id, and so does blurring a segment. The headline and the legend use a short form: 1,000 and up become a "k" value, one decimal below 100,000 and none from there up, with a trailing ".0" removed. The hover line does not shorten. It prints the full grouped number, so Files stays 46,500 there while the legend can read 46.5k. The idle percent is the rounded ratio of used to contextWindow. On the demo's first paint the parts sum to 100,400, the headline shortens that to "100k" because 100,000 and above drop the decimal, and the idle line reads 50 percent full of a 200k window. The demo does not pass model, so the default sample name shows under the heading. Reduced motion skips the entrance scale on the bar. Segment clicks do not remove a part. They only reveal the detail you already attached.
Choosing a layout
Place it where someone can still remove something: a composer with files attached, a project panel full of tool definitions, or the inspector beside a long thread. The useful moment is before older turns get summarised, which is the promise written on the Free segment. A ring of the whole allowance cannot say that Files are a large slice and Tools are a smaller one. The stacked bar can, because each slice keeps its color and its own sentence. The demo's four colors match the gradient used on Usage meter's ring, so the two can sit in one product without inventing a second palette.
Skip it on a billing page. A weekly credit chart does not care which message held the schema. Usage meter's daily bars already answer the week, split into Chat, Code, Agents, and Images. Skip it as the only warning when the person is simply out of plan messages. Quota banner carries the reset time and the upgrade action for that. Use the breakdown when the next click should detach a file or drop a server, and when you already know the token count of each part. The component does not tokenize text. It only lays out the numbers, and it will draw a zero Free hatch if the parts already overflow the window.
Is Free one of the parts passed in?
No. ContextBreakdown builds it after summing parts. Its id is "free", its name is "Free", and its detail string is hard-coded. You do not pass a color for it. The legend draws an empty swatch with a border instead of a filled square. If the parts already add up to more than contextWindow, free tokens become 0, and the 3 pixel minimum can still leave a hairline hatch. Hovering that hairline reports 0 tokens and 0.0 percent rather than hiding the row.
Why can the big total and a segment's percent look like different math?
They are rounded differently on purpose. The headline and the legend run the short formatter, so 100,400 paints as "100k" and 11,800 paints as "11.8k". The idle line uses a whole percent of the window. The hover line keeps the raw token count and one decimal, so Files at 46,500 of 200,000 reads 23.3 percent there even while the headline has collapsed the overall total. Pass contextWindow in the same unit as each part's tokens. The prop comment calls it the total context window, in tokens. The component never converts characters to tokens for you.