Context meter · Interaction component

<UiContextMeter />· loading

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.

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 the aria-label "Context window N% full".
The aria-label is fixed English and does not use label.
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.

<ui-odometer>

Odometer stepperui-odometer

<effort-slider>

Ultracode slidereffort-slider

<ui-thinking>

Thinking indicatorui-thinking

<ui-send-button>

Send / stop buttonui-send-button

Related