# Usage meter

A React component in [Beamline](https://beamline.io/)'s [Feedback](https://beamline.io/components/feedback) category, in the free sample. Live demo: https://beamline.io/components/usage-meter

An allowance and what fills it: one bar split by source, the room left, a warning near the limit and the overflow in its own red well past a notch at the limit.

## Use it for

- Plan limits and quotas: seats, storage, requests.

## Not for

- Task progress ([progress](https://beamline.io/components/progress)).
- A single value on a range ([gauge](https://beamline.io/components/gauge)).

## Anatomy

- header (label, figure with a status glyph when warn/over)
- bar: allowance well (m-inset meter, sources in series colours up to the limit)
- notch at the limit and overflow well (solid red), only when over
- legend (swatch, label, value; room left or overflow with glyph and words)

## States

- ok
- warn (orange figure + ▲ glyph)
- over (red figure + ⓘ glyph, overflow well after the notch, 'N over' in the legend)

## Keyboard

- Not interactive (role meter)

## Motion

Segment widths ease over --pui-duration-standard when values change; nothing moves at rest. When the value changes, the change itself stays in view for a moment (_shared/delta-ghost): what was lost sits as a pale ghost under the fill, holds about 0.7 s and drains toward the new end; what was gained arrives lit and cools over about 1.3 s. The ghost spans the real before and after, never an in-between value; a run of changes the same way extends one ghost. Reduced motion: the ghost is shown still for 1.1 s, then removed.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — |  |
| `segments` | `{ id, label, value }[]` | — |  |
| `limit / unit / decimals` | `number / string / number` | — |  |
| `warnAt` | `0–1` | — |  |
| `freeLabel / overLabel` | `string` | — |  |
| `style / ref` | `CSSProperties / native Ref` | — | native HTMLDivElement |
| `classNames` | `UsageMeterClassNames` | — |  |

## Import

```tsx
import { UsageMeter } from "@/components/usage-meter/usage-meter";
```

## Get it

Usage meter is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. Usage meter is in the free sample, which costs nothing. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Feedback

- [Alert](https://beamline.io/components/alert): A message that stays until it is dealt with: what happened, what to do, an action; danger and warning are announced; dismissing folds its height away.
- [Announcement bar](https://beamline.io/components/announcement-bar): A banner across the top for news and offers: messages take turns, a countdown ticks, and dismissing folds it away and can remember it.
- [Empty state](https://beamline.io/components/empty-state): What a place will hold and the first step to fill it, instead of a blank; a compact size for panels and filtered tables.
- [Notification centre](https://beamline.io/components/notification-center): Updates that wait to be read: a bell with the unread count opens All / Unread, new and earlier groups, and per item mark read or dismiss.
- [Progress](https://beamline.io/components/progress): How much of a known task is done, or a moving bar when the length is unknown, with an optional label and value.
- [Skeleton](https://beamline.io/components/skeleton): Holds the shape of content while it loads, then crossfades into it, so nothing jumps.
- [Spinner](https://beamline.io/components/spinner): A ring that spins while work runs and closes into a drawn check or cross when it ends.