The plan with dialogs to change or cancel it, what this period costs so far and where it's heading against the budget and alerts, usage with what going past each limit costs, spend alerts by email or Slack, the card on file and invoices. On motion.
Installation
When to use
- The billing page of a subscription product: the plan with dialogs to change or cancel it, what this period costs so far and where it's heading, usage against the plan's limits, spend alerts, the card on file and invoices.
- Usage-based pricing, where people need to see a bill coming before it arrives and decide whether to upgrade.
When not to use
- One-time purchases without a subscription: an order history fits better.
- Picking a plan for the first time: Pricing tiers.
- What an AI feature costs by model and API key: AI usage & limits.
Usage
Billing settings with your own data: every prop has the sample as its default, so pass only what you have.
"use client"
import { useState } from "react"
import { BillingSettings, type Billing, type BillingAlert } from "@/components/dashral/blocks/billing-settings"
export default function Billing() {
// Your alerts, kept in state: onAlertsChange hands you the whole list after each change.
const [alerts, setAlerts] = useState<BillingAlert[]>([{ id: "a1", amount: 500, channels: ["email"] }])
return (
<BillingSettings
plan="growth"
billing="monthly"
renews="Dec 1, 2026"
meters={[
{ id: "events", label: "Events", used: 8_420_000, limit: 10_000_000, projected: 10_500_000, overage: "$2 per extra million" },
{ id: "seats", label: "Seats", used: 6, limit: 20 },
]}
// What this period has cost so far, one number a day; the last is today.
spend={{ days: [38.2, 41.5, 40.1, 44.9, 39.7], start: "2026-11-01", length: 30, budget: 1500 }}
alerts={alerts}
card={{ brand: "Visa", last4: "4242", expires: "08/28" }}
invoices={[{ id: "INV-2026-011", period: "October 2026", date: "Nov 1", amount: 249, status: "paid", href: "/invoices/INV-2026-011.pdf" }]}
// While a promise is pending its button shows it; a thrown Error changes nothing and its message shows at the top.
onChangePlan={async (plan, billing) => console.log("change to", plan, billing)}
onCancel={async (reason) => console.log("cancel", reason)}
onAlertsChange={async (next) => setAlerts(next)}
// A failed or due invoice offers Pay now; resolve when the payment went through.
onPay={async (invoice) => console.log("pay", invoice.id)}
onUpdatePayment={() => console.log("open your payment form")}
/>
)
}API reference
BillingSettings
A billing page: the plan with its renewal, a dialog to change it (monthly or yearly, with the saving) and one to cancel it (with a reason, and a way back), and a nudge to the next plan when usage is heading past its limits; what this period has cost so far and where it's heading against the budget and the alerts; usage against the plan's limits with what going past costs; the spend alerts and where they go; the card on file; and past invoices to download. Every part comes from props, and every action calls your handler first: one that throws changes nothing and says why at the top.
| Prop | Type | Default |
|---|---|---|
plans | BillingPlan[] | sample |
plan | stringThe plan you're on, by id, and how it's billed. | "growth" |
billing | Billing | "monthly" |
canceled | booleanWhether it's set to cancel at the renewal. | false |
renews | stringWhen it renews (or ends, once canceled). | "Dec 1, 2026" |
used | { seats: number; events: number; storage: number }What's used of the plan's limits (seats, events, storage in GB), for the three meters it then shows. | — |
meters | BillingMeter[]The meters, each with its limit, where it's heading and what going past costs. Left out (with | — |
usageNote | string | sample |
spend | BillingSpend | nullWhat this period has cost so far, day by day, and its budget; null leaves the spend out (as does passing | — |
alerts | BillingAlert[] | nullThe spend alerts, at first; null leaves them out (as does passing | — |
card | { brand: string; last4: string; expires: string } | nullThe card on file; null shows none. | sample |
billingEmail | string | "finance@acme.com" |
taxId | string | "ID 01.234.567.8-901" |
invoices | BillingInvoice[] | sample |
currency | string | "USD" |
locale | string | "en-US" |
onChangePlan | (plan: string, billing: Billing) => Promise<void> | void | — |
onCancel | (reason: string) => Promise<void> | voidCancels at the renewal, with the reason given (if any). | — |
onResume | () => Promise<void> | void"Keep my plan" after canceling. | — |
onUpdatePayment | () => void | — |
onDownload | (invoice: BillingInvoice) => voidAn invoice without an href: download it yourself. | — |
onPay | (invoice: BillingInvoice) => Promise<void> | voidPay an invoice that failed or is due: Pay now shows it's working while the promise is pending; on success it turns Paid, a throw says why. | — |
onAlertsChange | (alerts: BillingAlert[]) => Promise<void> | voidThe alerts after one is added, removed or has a channel turned on or off. Shown at once; a throw puts them back and says why. | — |
className | string | — |
BillingMeterRow
Where one thing the plan limits stands: what's used, where it's heading at this pace (striped), the limit, and what going past it costs. Near or past the limit, or heading past it, it says so.
| Prop | Type | Default |
|---|---|---|
meter | BillingMeterRequired. | — |
BillingSpendChart
The period's spend adding up, grown up from its axis when it first shows, going on dashed at this pace to the period's end, with the budget and each alert's amount drawn across it, named at the end.
| Prop | Type | Default |
|---|---|---|
spend | BillingSpendRequired. | — |
marks | number[]The alerts' amounts, drawn across the chart. | [] |
format | Intl.NumberFormatRequired. | — |
height | number | 180 |
className | string | — |
type Billing
= "monthly" | "yearly"type BillingPlan
A plan: its price a month (a year is ten months), its limits (storage in GB) and its icon.
| Prop | Type | Default |
|---|---|---|
id | string | — |
name | string | — |
monthly | number | — |
seats | number | — |
events | number | — |
storage | number | — |
icon | React.ReactNode | — |
type BillingInvoice
period ("October 2026") or title (what it was for: "Extra storage add-on") is the row's name when given, with detail under it (why a payment failed, when a transfer is due) or else the id. A "failed" or "due" invoice offers Pay now.
| Prop | Type | Default |
|---|---|---|
id | string | — |
date | string | — |
amount | number | — |
status | "paid" | "refunded" | "open" | "failed" | "due" | — |
href | string | — |
period | string | — |
title | string | — |
detail | string | — |
type BillingMeter
One thing the plan limits. projected is where it ends the period at this pace (striped on the meter); overage is what going past the limit costs, in words ("$2 per extra million"); format writes its numbers.
| Prop | Type | Default |
|---|---|---|
id | string | — |
label | string | — |
used | number | — |
limit | number | — |
projected | number | — |
overage | string | — |
format | (value: number) => string | — |
type BillingSpend
What this period has cost so far, a day at a time from start ("2026-11-01"), over a period of length days; the last is today.
| Prop | Type | Default |
|---|---|---|
days | number[] | — |
start | string | — |
length | number | — |
budget | number | — |
type BillingAlertChannel
= "email" | "chat"type BillingAlert
Says when spend passes amount, on its channels. sentAt is when it went off this period ("Nov 17").
| Prop | Type | Default |
|---|---|---|
id | string | — |
amount | number | — |
channels | BillingAlertChannel[] | — |
sentAt | string | — |