UsageMeter
StableHow many credits are left, with an optional cost estimate, reset date and upgrade button.
Also known as quota meter, usage bar, progress bar
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
With an estimate
This will use about 12 credits.
<UsageMeter remaining={340} total={500} estimate={12} resetText="Resets Nov 1" />Shows the cost before the person confirms an action.
When to use it
Shows how many credits are left and what the next action will cost, before it runs. It warns only when the person may need to act.
Made of: Remaining text · Reset time · Bar · Cost estimate · Warning text · Upgrade button
Use it for
- Before a paid action, to show about how much it will use.
- A plan's remaining allowance, with when it resets.
- Offering an upgrade once credits run low.
Not for
- How full the current chat is: use ContextMeter.
- A limit that has been reached and blocks the next request: use RateLimitNotice.
Do and avoid
This will use about 12 credits.
Do
- Show the estimate before the action runs.
- Show when the allowance resets.
- Offer the upgrade only when credits run low.
Avoid
- Do not use amber while there is plenty left.
- Do not hide retries that use up credits.
- Do not give an exact estimate you cannot back up. Say about.
On a phone
- The meter fills the width, with the amount on the left and the reset time on the right.
- The warning and your upgrade action share a row that wraps. A button gets a 44px tap area by itself. If your upgrade action is a small link, give it the tap class.
Seen in products
- Adobe shows generative credits, as its own FAQ describes.
- Runway shows credit cost per second before generating. Gen-4 is 12 credits per second and Turbo is 5.
- Notion limits complimentary AI responses and each retry counts.
- GitHub Copilot coding-agent steering messages consume AI credits.
- Replit confirms before paid actions.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| remainingrequired | number | none | Credits or quota left. |
| totalrequired | number | none | Full allowance for the period. |
| unit | string | "credits" | Plural unit name used in the text. |
| estimate | number | none | Cost of the pending action. Shows This will use about N credits. |
| resetText | string | none | Reset time, for example Resets Nov 1. |
| warnAt | number | 0.8 | Fraction used, 0 to 1, at which the meter warns. |
| upgrade | ReactNode | none | Slot for an upgrade action, shown only in the warn state. |
| warnText | string | none | Overrides the reason in the warn state. |
| label | string | "Usage" | Accessible name of the meter. |
| className | string | none | Extra classes on the wrapper. |
"Show code under the preview gives the code for the example on the stage."
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- running low
- When the used share reaches warnAt, the bar warns and a running-low message shows with the optional upgrade slot.
- not enough
- When estimate is more than remaining, the bar turns attention-coloured and says there is not enough left.
- estimate
- Pass estimate to show how much this action will use.
Tokens
Change one of these and every part that uses it follows.
--attention--attention-fg--fg--fg-subtle
Built in
- The bar is a named meter that screen readers read as "N of M credits left".
- The estimate and the warning are written out, so color is not the only clue.
- The warning says why, such as running low or not enough left for this.
- The bar's grow-in motion stops when people turn off motion in their system settings.
What you need to do
- Put a real button or link with a clear name in the upgrade slot.
- Place the meter before the action it estimates, so the cost is heard before the action.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide