Credit balancePro

A credit pill whose digits roll when the balance changes, amber and red low and empty states with labels, and a popover with spend by action, the latest spend and a top up button.

Markdown

On this page

ProSpend and top up to watch the digits roll, the delta float by and the low and empty states arrive.

Installation

$ pnpm dlx shadcn@latest add @chatcn-pro/credit-balance

Usage

tsx

import { CreditBalance } from "@/components/ui/chatcn/pro/credit-balance"

<CreditBalance
  balance={account.credits}
  spend={account.recentSpend}
  renewal={{ amount: 2000, at: account.renewsAt }}
  onTopUp={() => setTopUpOpen(true)}
/>

At or under lowAt (default 100) the pill turns amber and says Low; at zero it turns red and says No credits. The icon changes too, so the state never depends on color. The popover groups spend by action and lists the latest four entries with relative times.

RollingNumber is exported for any number that changes: it rolls each digit to its new value, never animates on mount, and reads as one formatted number to screen readers.

Examples

States

ProNormal, low, empty, loading, failed spend, no spend yet and the small size.

Props

Prop	Type	Notes
`balance`	`number`
`unit`	`string`	Default credits
`lowAt`	`number`	Default 100
`spend`	`CreditSpend[]`	`id`, `action`, `credits`, `at`, `detail?`. Newest first
`periodLabel`	`string`	Default Last 7 days
`forecast`	`ReactNode`	A line under the balance
`renewal`	`{ amount, at }`	Credits that arrive with the plan
`onTopUp`, `topUpLabel`, `onViewUsage`		Footer actions
`loading`, `error`, `onRetry`		States
`size`	`"sm" \| "md"`	28 or 32 px
`showDelta`	`boolean`	Float the change next to the pill. Default true
`open`, `defaultOpen`, `onOpenChange`	`boolean`
`locale`	`string`	Number and date formatting
`labels`	`Partial<CreditBalanceLabels>`	Every string the credit balance shows or announces, for translation

Keyboard

Key	Action
`Enter`, `Space`	Open the details
`Tab`	Move to View usage and the top up button
`Escape`	Close

Accessibility

The pill's name starts with what it shows, then the state: 48, low on credits. Show credit details.
Rolling digits are hidden from assistive tech; the formatted value is read once.

Motion

Each digit rolls on its own column in 280 ms ease-out, transform only. Nothing rolls on mount.
The delta fades in and out over 1.4 s next to the pill. The popover grows from the pill in 180 ms.
Reduced motion swaps digits at once and drops the delta.