# Usage Planner block

> Usage planner with a stepped token ruler, model cards and a live spend estimate

Plan next month's AI spend: a stepped token ruler with graduated volume discounts, model cards, add-on chips and a projected total against a monthly budget. ReUI Frame, Badge; shadcn Slider, RadioGroup, ToggleGroup, Switch, DropdownMenu, Tooltip; Motion. Usage pricing, AI billing.

- Type: Pro block
- Category: [AI Usage](https://reui.io/blocks/ai-agents/ai-usage.md)
- Page: https://reui.io/blocks/ai-agents/ai-usage/ai-usage-1
- MCP: `get_block("ai-usage-1")`
- Built with: Avatar, Badge, Button, Dropdown Menu, Field, Frame, Radio Group, Separator, Slider, Switch, Toggle Group, Tooltip
- Installs with a ReUI Pro or Ultimate license; setup: https://reui.io/docs/license-setup

## Best for

A self-serve page where a workspace admin sets next month's token volume, model and add-ons and sees the bill against a budget

## Agent notes

- Bands, models, add-ons and the budget live in `TIERS`, `MODELS`, `ADDONS` and `BUDGET`; every figure in the spend panel comes from `buildQuote`
- Each `TIERS` band edge must be an exact value in `STOPS`, the slider's 81 steps from 1M to 10B, or the band row loses its place
- `onSave` and `onContact` only fire a sonner `toast`, seen once your app mounts a Toaster; send the plan to your billing API there

## When not to use

- Public plan tiers and an upgrade path on a public site, with no usage to plan: use the [Pricing blocks](https://reui.io/blocks/marketing/pricing.md)

## Third-party libraries

- Motion v12: [API reference](https://motion.dev/docs/react-motion-component), [docs](https://motion.dev/docs/react) (the docs follow the latest Motion, with no React API break since v12)
- Sonner v2: [API reference](https://sonner.emilkowal.ski/toast), [docs](https://sonner.emilkowal.ski/getting-started)

## Install

```bash
npx shadcn@latest add @reui/ai-usage-1
```

## About AI Usage blocks

### When to use

- A self-serve planner where an admin sets next month's token volume, model and add-ons against a budget
- A month to date breakdown of AI spend by model, team, agent and API key, with the caps at risk
- A budget, run rate or volume discount readout inside an AI product's own account area

### When not to use

- Staff back office for invoices, subscriptions, dunning and metered charges: use the [Billing blocks](https://reui.io/blocks/solutions/billing.md)
- Public plan tiers or an upgrade paywall shown before anyone has usage: use the [Pricing blocks](https://reui.io/blocks/marketing/pricing.md)
- An operator console for provider health, routing and quotas across an org: use the [AI Ops blocks](https://reui.io/blocks/solutions/ai-ops.md)

### Agent notes

- `AiUsage` takes no props and calls no API; every figure comes from typed constants in components/data.tsx, so swap them for your data
- Money prints through en-US USD helpers such as `formatDollars` in formatters.ts, so another currency starts there

Every ReUI item has a twin like this one; the index is https://reui.io/llms.txt. Agents with the ReUI MCP (https://reui.io/docs/mcp) get the same guidance from the getters named above.