Staaarter

Billing Credit Balance

A small card widget showing the account's current credit balance as a large total, an optional line-item breakdown by source, and a low-balance notice with a top-up button. Sized for a dashboard sidebar or an AI/usage-based billing portal rather than a full billing page.

By Staaarter Team
Billing
Updated June 3, 2026
Docs
Live preview

Docs

Installation

A real shadcn registry command, not a copy-paste stand-in: it fetches this block plus its card, button dependencies and any missing npm packages, and installs them straight into your project.

npx shadcn add https://staaarter.com/r/billing-credit-balance.json

Prefer not to use the CLI? Copy the source from the Code toggle above into src/components/blocks/billing/billing3.tsx instead.

Usage

The file also exports billing3Demo, the exact props behind the preview above. Spread it to get a working section in one line, then replace it with your own data.

import { Billing3, billing3Demo } from "@/components/blocks/billing/billing3";

export default function Page() {
  return <Billing3 {...billing3Demo} />;
}

Props

PropTypeDefaultDescription
balancestringnoneThe large total shown at the top of the card, already formatted as currency.
breakdownCreditBreakdownItem[]noneOptional line items (e.g. purchased vs. promotional) listed under the total; the list is omitted entirely when not passed or empty.
lowBalancebooleanfalseShows the amber low-balance notice when true.
lowBalanceMessagestring"Your balance is running low."Text shown inside the low-balance notice.
topUpLabelstring"Add credit"Label for the footer button.
topUpHrefstringnoneDestination for the footer button.
classNamestringnoneExtra classes for the outer card.

Types

interface CreditBreakdownItem {
  label: string;
  amount: string;
}

Behavior notes

  • balance is a pre-formatted string, not a number, so currency symbol and decimal formatting are entirely the caller's responsibility.
  • The breakdown list renders only when the array is passed and non-empty; there's no default line items and no total-reconciliation check against balance.
  • The low-balance notice is a plain conditional block driven by the lowBalance prop, not a computed threshold. Decide the threshold logic on the server or in the parent component.
  • The footer button always renders and always points at topUpHref, there's no way to hide it short of not rendering the block.
  • Card width is capped at max-w-xs so it reads as a sidebar or dashboard-grid widget rather than a full-width section.

Frequently asked questions