Skip to main content
Clever Ops

Context Meter

Context-window usage meter, a hairline bar with a tabular tokens-used/limit readout and per-source breakdown rows, shifting to an honest warning treatment at 85 percent.

Preview & code

Loading Context Meter preview

Installation

pnpm dlx shadcn@latest add @cleverui/context-meter

Requires the @cleverui registry in your components.json, a one-off, two-line setup.

Usage

tsx
import { ContextMeter } from '@/components/ui/context-meter'
Exampletsx
'use client'

import { useEffect, useState } from 'react'
import { useReducedMotion } from 'motion/react'
import { ContextMeter } from '@/components/ui/context-meter'

type UsageFrame = {
  used: number
  system: number
  tools: number
  history: number
}

const FIRST_FRAME: UsageFrame = {
  used: 42_800,
  system: 4_200,
  tools: 8_400,
  history: 30_200,
}

const STEPS: UsageFrame[] = [
  FIRST_FRAME,
  { used: 78_600, system: 4_200, tools: 14_100, history: 60_300 },
  { used: 128_402, system: 4_200, tools: 18_600, history: 105_602 },
  { used: 174_200, system: 4_200, tools: 22_400, history: 147_600 },
  { used: 188_900, system: 4_200, tools: 24_100, history: 160_600 },
]

const LIMIT = 200_000

export default function ContextMeterDemo() {
  const reduced = useReducedMotion()
  const [step, setStep] = useState(0)
  const frame = STEPS[step] ?? FIRST_FRAME

  useEffect(() => {
    if (reduced) {
      // settled high-water state under reduced motion
      setStep(STEPS.length - 1)
      return
    }
    const id = window.setInterval(() => {
      setStep((s) => (s + 1) % STEPS.length)
    }, 2200)
    return () => window.clearInterval(id)
  }, [reduced])

  return (
    <div className="mx-auto flex min-h-[380px] w-full max-w-lg flex-col justify-center px-4 py-16 sm:px-6">
      <div className="rounded-2xl border border-border/60 bg-card p-5 sm:p-6">
        <div className="mb-6">
          <p className="font-mono text-[11px] uppercase tracking-[0.2em] text-muted-foreground sm:text-xs">
            meridian-ops · session
          </p>
          <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
            Token budget for the March close run against Apex Holdings.
          </p>
        </div>
        <ContextMeter
          used={frame.used}
          limit={LIMIT}
          label="Context"
          warnAt={0.85}
          breakdown={[
            { label: 'system', tokens: frame.system },
            { label: 'tools', tokens: frame.tools },
            { label: 'history', tokens: frame.history },
          ]}
        />
      </div>
    </div>
  )
}

API reference

ContextMeter accepts the following props.

PropTypeDefaultDescription
used*numbertokens consumed; updates are prop-driven
limit*numbercontext-window size in tokens
breakdownContextMeterBreakdown[]per-source rows; omit to render bar and readout alone
warnAtnumber0.85fraction of limit at which warning treatment engages
labelstring'Context'mono micro-label before the readout

…plus everything from React.HTMLAttributes<HTMLDivElement>: className, event handlers, aria attributes and the rest pass straight through.

Referenced types

Typestsx
export interface ContextMeterBreakdown {
  label: string
  tokens: number
}

Frequently asked questions

How do I install the Context Meter component?

Register the @cleverui registry in your components.json ("@cleverui": "https://cleverops.com.au/r/{name}.json"), then run `npx shadcn@latest add @cleverui/context-meter`. The shadcn CLI copies the source into your project, you own the code from that point. You can also copy the source directly from this page.

What dependencies does Context Meter require?

Context Meter uses motion on top of React and Tailwind CSS. You don't need to install it manually, the shadcn CLI resolves and installs npm dependencies automatically when you add the component.

Can I theme Context Meter to match my brand?

Yes. The component is styled entirely with Tailwind utilities over standard design tokens (primary, background, muted, border), so it inherits your existing shadcn/ui theme automatically. Change your CSS variables and the component follows, no source edits needed for palette, radius, or fonts.

Want this built for you?

CleverUI is built by the Clever Ops web team. If you'd rather ship a hand-coded, fast, custom website than assemble one, we build them for Australian businesses every week.

Explore web development services