Usage billingPro

• Type: Block

• Page: https://ui.xzero.co.uk/components/blocks/usage-billing

• Markdown: https://ui.xzero.co.uk/components/blocks/usage-billing/markdown

• Access: Xzero Pro

• Registry id: usage-billing

• Source file: registry/blocks/usage-billing/usage-billing.tsx

• Built from: Animated counter, Text morph, Button

• Keywords: usage billing, metered billing, spend dashboard, projected spend, usage limits, spend alerts, budget alerts, invoice history, upgrade plan, proration

Use this in the billing area of a usage priced product. Load meters, daily spend, and invoices from your billing provider, save alerts through onAlertsChange, and send the upgrade to your checkout; every charge in the preview is simulated.

When to use

• A billing page for usage priced SaaS or infrastructure products.
• Admin dashboards where finance needs spend alerts and invoice history in one place.
• Upgrade moments driven by limits, where the upgrade should explain what changes.

When not to use

• Use billing-overview for flat seat based plans without meters.
• Use plan-comparison or usage-pricing on a public pricing page.
• Avoid it for a single quota; a usage meter component is enough.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/usage-billing

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { UsageBilling } from "@/components/xzero/blocks/usage-billing/usage-billing";

export function BillingPage({ usage, plans }: { usage: BillingSnapshot; plans: PlanCatalog }) {
  return (
    <UsageBilling
      period={usage.period}
      daily={usage.dailySpend}
      meters={usage.meters}
      plan={plans.current}
      upgrade={plans.next}
      defaultAlerts={usage.alerts}
      onAlertsChange={alerts => saveAlerts(alerts)}
      onUpgrade={plan => startUpgrade(plan.id)}
      onDownloadInvoice={invoice => downloadPdf(invoice.id)}
    />
  );
}

API reference

UsageBilling

A usage based billing dashboard: spend so far with a projected line and live alert rules on the chart, per meter usage against limits with warning states, a spend alerts editor, invoice history with downloads, and a plan card that grows into an upgrade confirm sheet.

Prop	Type	Default	Description
period	{ label: string; start: string; days: number; today: number }	billingPeriod	The current billing period and which day it is.
daily	number[]	dailySpend	Usage charges per day so far. Its length is the number of days elapsed.
budget	number	2000	Monthly budget drawn on the chart.
meters	Meter[]	meters	Metered resources: id, name, unit (requests, gigabytes, minutes, invocations, seats), used, limit, and an overage price label.
plan	Plan	currentPlan	The current plan: name, monthly price, limits keyed by meter id, and perks.
upgrade	Plan | null	upgradePlan	The plan offered in the upgrade card. Pass null to hide the offer.
defaultAlerts	SpendAlert[]	spendAlerts	Initial alerts: amount, email, and slack.
onAlertsChange	(alerts: SpendAlert[]) => void	–	Called whenever alerts are added, edited, or removed.
invoices	Invoice[]	invoices	Past invoices with number, period, issue date, amount, and status.
payment	{ brand: string; last4: string; expires: string }	paymentMethod	Card shown on the plan card, the invoices header, and the confirm sheet.
onUpgrade	(plan: Plan) => Promise<void> | void	–	Runs the upgrade. Resolve to switch plans, reject to show a declined message. Without it the upgrade is simulated.
onDownloadInvoice	(invoice: Invoice) => Promise<void> | void	–	Fetches an invoice PDF. Without it the download is simulated.
currency	string	"EUR"	ISO currency code for every amount.
className	string	–	Class on the root.

Keyboard interactions

Keys	Action
Tab	Moves through the chart, plan card, alerts, and invoice downloads.
Arrow left / Arrow right	Moves the chart cursor one day at a time while the chart has focus.
Enter in an alert amount	Commits the amount; alerts re sort by amount when the field loses focus.
Escape	Closes the upgrade sheet unless a payment is in progress.

Accessibility

• The chart is an image with a spoken summary of spend, projection, and budget; its cursor also works from the keyboard.
• Each meter is a meter role with a value text that says when it is near or projected over the limit.
• Warnings pair an icon and words with color. Invoice status pairs a dot with a label.
• The upgrade sheet is a modal dialog that traps Tab, focuses its heading, and returns focus to the plan card.
• The sheet states that the preview takes no payment.

Motion

• The spend line draws in once, the projection and alert rules follow; alert rules glide to their new height while you type an amount.
• Meter bars fill with a short stagger. After an upgrade every limit grows, so the bars shrink and warnings clear in place.
• The plan card grows into the confirm sheet on one spring and folds back into the card once the upgrade lands.
• Invoice downloads swap their icon for a spinner, then a check, without changing width.
• Reduced motion removes the draw in, stagger, and flight, and keeps short fades.

Responsive behavior

• From 700px the chart and plan card share a row, and meters sit beside alerts.
• Below 520px the invoice issue date and overage prices hide; everything else stacks.
• The confirm sheet keeps a 12px margin and stays clear of sticky page chrome.

Performance

• The chart is one SVG sized from a ResizeObserver; hover updates only the cursor and tooltip.
• Bars animate transform scale only.
• Sheet flight animates one element's transform and size.

Notes for AI

• Choose it for products billed on usage: API calls, compute, storage, bandwidth, seats.
• Feed daily spend from your billing provider; the projection is the average of the last seven days carried to the end of the period.
• Set plan limits per meter id so the upgrade can recompute every bar.
• Call your checkout or subscription update API in onUpgrade and reject on a declined card.

Related

• Billing overview: A billing page where the plan card morphs into a picker and usage, invoices, and card follow.
• Usage forecast: A billing period usage chart with a forecast cone and a draggable budget that dates the crossing.
• Usage pricing: A pricing calculator that finds your plan as you drag seats and traffic.
• Plan comparison: Compare meaningful differences between plans and billing periods.
• Usage meter: Show what fills an allowance and how close it is to the limit.

Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt