# Usage Meter

> Usage card with a segmented meter coloured by resource, a hatched projection and animated totals; the monthly budget slider rescales every segment live.

- Collection: AI Agents
- Tier: pro
- Docs: https://geturui.com/docs/usage-budget
- Install: `npx shadcn@latest add @geturui-pro/usage-budget`
- Dependencies: motion, lucide-react

## Variants

### Segmented meter

Segments fill by resource with a staggered spring; hover a resource to isolate its share, drag the budget to rescale.

Install: `npx shadcn@latest add @geturui-pro/usage-budget-segmented-meter`

```tsx
import { SegmentedUsageMeter } from "@/components/ai/usage-budget/segmented-meter";

export function Billing() {
  return (
    <SegmentedUsageMeter
      resources={[
        { id: "chat", name: "Chat completions", usage: "4.1M tokens", cost: 92.4, tone: "volt" },
        { id: "images", name: "Image generation", usage: "412 images", cost: 41.2, tone: "ember" },
      ]}
      defaultBudget={250}
      projected={160}
      onBudgetChange={saveBudget}
    />
  );
}
```

| Prop | Type | Default | Description |
|---|---|---|---|
| resources | `UsageResource[]` | DEFAULT_RESOURCES | { id, name, usage, cost, tone? } in meter order. |
| budget / defaultBudget | `number` | 250 | Controlled or initial monthly budget in dollars. |
| onBudgetChange | `(budget: number) => void` | — | Called as the slider moves. |
| minBudget / maxBudget / step | `number` | 50 / 1000 / 10 | Slider range. |
| projected | `number` | 238 | Forecast spend, drawn as hatched segments. |
| alertAt | `number` | 0.8 | Fraction of budget that switches to the warning state. |
| segments | `number` | 40 | Number of segments. |
| periodLabel | `string` | — | Billing period line under the title. |

## Accessibility

- The segmented bar is a role="meter" with a spoken value such as “$184.20 of $250.00, 74 percent”.
- The budget slider is a native range input with a dollar aria-valuetext; arrows and Page keys adjust it.
- Status is always an icon plus words (On track, 82% of budget used, Over by $12.00), never colour alone.

## Source

Pro item — send `Authorization: Bearer <registry token>` to include the source.