Skip to content
NewYour data: charts, lists and meters that take your records
<UiContextMeter />ReactData

Context meter

Context-window meter that fills a pixel strip behind a glowing front, turns amber at 80% and red at 95%, and animates compaction.

View as Markdown
<UiContextMeter />

Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

Loading <UiContextMeter />
Props
defaultValueremounts
capacitylive
labellive
React
<UiContextMeter defaultValue={46} capacity={200000} label="Context" />

Installation

pnpm dlx shadcn@latest add @lumesec/ui-context-meter
First timeRegister the @lumesec registry once, or install by URL

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/ui-context-meter.json

Usage

ui-context-meter-example.tsx
"use client";

import * as React from "react";

import { UiContextMeter, type UiContextMeterHandle } from "@/components/lumesec/ui-context-meter";

export function Example() {
  const meter = React.useRef<UiContextMeterHandle>(null);
  return (
    <div className="grid gap-3">
      <UiContextMeter ref={meter} defaultValue={46} capacity={200000} />
      <button type="button" onClick={() => meter.current?.compact()}>
        Compact
      </button>
    </div>
  );
}

Behaviour

Usage fills a strip of pixels behind a glowing front, turns amber past 80 % and red near the limit. Compacting sends a bright band back across the strip as the count drops.

API reference

Props

Also accepts every prop of <div> (React.ComponentProps<"div">), spread onto the root element.

valueTypenumber

Controlled share of the context window in percent, clamped to 0–100. The strip animates to each new level. Use with onValueChange.

defaultValueTypenumberDefault0

Initial percentage when uncontrolled.

capacityTypenumberDefault200000

Window size in tokens, used only for the "used / total" readout, which is shown in thousands.

labelTypestringDefault"Context"

Caption before the percentage, and the meter's accessible name.

onValueChangeType(value: number) => void

Called with the new percentage when add() or compact() changes it.

onCompactType(from: number, to: number) => void

Called when compact() runs, with the percentage before and after.

refTypeReact.Ref<UiContextMeterHandle>

Exposes add() and compact().

Ref

ref receives a UiContextMeterHandle handle with these methods.

add(percent: number): void

Adds percent percentage points (negative to subtract), clamped to 0–100.

compact(): void

Drops usage to 28% of its current value (at least 12%), runs a bright sweep and shows "Compacting…" for 1.5 s. Does nothing at 15% or below.

Accessibility

  • The strip is a canvas with role="meter", aria-valuemin="0", aria-valuemax="100", aria-valuenow and an aria-label from label.
  • Its aria-valuetext reads the level and the token count, for example "46%, 92,000 of 200,000 tokens" (built in English).
  • There is no live region; changes are not announced.
  • Reduced motion: the fill jumps to the new level, the compaction sweep is skipped, the percentage stops blinking near the limit and text swaps without rolling.

Theming

Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --lumesec, --lumesec-glint, --lumesec-warning, --destructive, --foreground and --muted-foreground.

Notes

  • value is a percentage, not a token count; the token readout is derived from capacity.
  • The root carries data-zone set to ok, warn (80% and up) or full (95% and up), which can be used for styling.
  • The strip is 18 px tall and fills the available width. Its colours follow the theme and are re-read when it changes.

Was this page helpful?