Usage Chart Block React component
A usage panel for metered plans: daily stacked bars by source with a daily budget line, a cumulative view with the plan limit and a dashed projection to cycle end, used / projected / overage figures, a status line that names the day you will pass your limit, hover breakdowns and legend toggles.
About the Usage Chart Block component
Usage Chart Block answers the questions people have about a metered plan: how much have I used, where is it coming from and will I go over? Daily bars are stacked by source, so you can see which endpoint, job or service drives the bill, with a line for the daily budget that keeps you within the limit.
Switch to Cumulative to see the running total against the plan limit, with a dashed line projecting where you will end the cycle at the current pace. The summary shows what has been used, what is projected and what the overage would cost, and a status line names the day you would pass the limit.
When to use it
Use it on billing and usage pages of API products, hosting and infrastructure dashboards, or any plan with quotas.
Keep each metric to four or five series and group the long tail as Other.
Installation
Add the Usage Chart Block component to your project with the shadcn CLI. It lands in components/usage-chart.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/usage-chartOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<UsageChart /> accepts 7 props, all optional.
| Prop | Type | Default |
|---|---|---|
| title | string | "Usage" |
| metrics | { id: string; label: string; unit: string; limit: number; overagePrice?: number; series: UsageSeries[] }[] | DEFAULT_METRICS |
| cycleStart First day of the billing cycle, YYYY-MM-DD. | string | "2026-10-10" |
| cycleDays Days in the cycle. | number | 31 |
| currency | string | "$" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- titlestringDefault: "Usage"
- metrics{ id: string; label: string; unit: string; limit: number; overagePrice?: number; series: UsageSeries[] }[]Default: DEFAULT_METRICS
- cycleStart
First day of the billing cycle, YYYY-MM-DD.
stringDefault: "2026-10-10" - cycleDays
Days in the cycle.
numberDefault: 31 - currencystringDefault: "$"
- theme"dark" | "light"Default: "dark"
- classNamestring
npm dependencies
Installed for you by the shadcn CLI.
Usage Chart Block FAQ
- How is the projection worked out?
- It takes the average of the last seven days and adds it for every remaining day in the cycle. The status line uses the same pace to find the day the running total crosses the limit.
- What is the red line in Daily view?
- The daily budget: the plan limit divided by the days in the cycle. Bars above it mean that day used more than its share.
- What data do I pass?
- For each metric, a limit and one array of daily values per series, from the first day of the cycle until today. Future days are drawn as ghost bars automatically.
- Can I hide a series?
- Yes. Click its legend chip in Daily view. The last visible series cannot be hidden, and the tooltip totals only what is shown.
- Is it accessible?
- The chart has a text summary with used, limit and projection, the status line is a status region, the usage bar is a progressbar, and the metric, view and legend controls are radio and toggle buttons.
