Spend alertPro

• Type: Block

• Page: https://ui.xzero.co.uk/components/blocks/spend-alert

• Markdown: https://ui.xzero.co.uk/components/blocks/spend-alert/markdown

• Access: Xzero Pro

• Registry id: spend-alert

• Source file: registry/blocks/spend-alert/spend-alert.tsx

• Built from: Switch, Button

• Keywords: spend alert, budget alert, billing threshold, usage alert, cost alert, ai spend, slack notification preview, pagerduty, hard stop, budget settings

Drop SpendAlert into a billing or usage settings page. Pass spend and period from your usage API (the forecast is projected for you unless you pass forecast), set the starting defaultValue (budget, threshold, channels, hardStop), and set destinations for your email, Slack channel and PagerDuty service. Wire onSave and onSendTest: each receives the settings and an AbortSignal, and the card handles the loading, saved, error and unsaved-changes states. Without handlers, both actions are simulated and the live region says so. onChange reports every edit.

When to use

• Letting a team set a monthly budget and alert threshold for metered spend.
• Showing how close current and forecast spend are to an alert line.
• Choosing where cost alerts go and previewing the Slack message before saving.

When not to use

• Read-only usage reporting with no settings; use usage-forecast or usage-billing instead.
• Per-seat plans with no metered spend.
• Complex multi-budget policies across many projects; use a table of budgets that opens this card per row.

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/spend-alert

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 { SpendAlert } from "@/components/xzero/blocks/spend-alert/spend-alert";

export function BillingAlerts({ usage }: { usage: { spend: number } }) {
  return (
    <SpendAlert
      project="Production"
      spend={usage.spend}
      defaultValue={{ budget: 5000, threshold: 80 }}
      destinations={{ email: "finance@acme.com", slack: "#eng-spend" }}
      onSave={async (settings, signal) => {
        const response = await fetch("/api/budget-alerts", { method: "PUT", body: JSON.stringify(settings), signal });
        if (!response.ok) throw new Error("Save failed");
      }}
    />
  );
}

API reference

SpendAlert

Budget and spend alert settings in one card: a monthly budget, a threshold slider drawn on the live spend bar, Email, Slack and PagerDuty toggles, a hard stop switch, and a live preview of the Slack message the alert posts. Renders the full demo with no props.

Prop	Type	Default	Description
title	string	"Spend alerts"	Card title.
project	string	"Production"	Project or workspace the budget applies to. Used in the subtitle and the Slack message.
scope	string	"Model API usage"	What is being metered, shown in the subtitle.
spend	number	3412.8	Spend so far this period, drawn as the solid fill on the bar.
forecast	number	–	Projected spend at period end, drawn as the lighter fill. Defaults to a linear projection from spend and period.
period	{ label: string; short: string; day: number; days: number; resetsOn: string }	{ label: "October", short: "Oct", day: 27, days: 31, resetsOn: "Nov 1" }	Billing period used for the forecast, the crossing date and the reset copy.
currency	string	"USD"	ISO 4217 currency code for formatting.
defaultValue	Partial<SpendAlertSettings>	{ budget: 5000, threshold: 80, channels: { email: true, slack: true, pagerduty: false }, hardStop: false }	Initial settings. Missing fields fall back to the demo defaults.
markers	number[]	[50, 80, 100]	Threshold markers on the bar. The thumb snaps to them within 2% while dragging, and PageUp or PageDown jumps between them.
destinations	Partial<Record<"email" | "slack" | "pagerduty", string>>	{ email: "finance@acme.com", slack: "#eng-spend", pagerduty: "Platform on-call" }	Where each channel delivers. PagerDuty pages only at 100%.
appName	string	"Acme Billing"	Sender name in the Slack preview.
lastSaved	string	"Last edited Oct 24 by Maya Chen"	Footer copy while nothing has changed.
onChange	(settings: SpendAlertSettings) => void	–	Called on every edit.
onSave	(settings: SpendAlertSettings, signal: AbortSignal) => Promise<void>	–	Persist the settings. Without it the save is simulated. Reject to show the error state.
onSendTest	(settings: SpendAlertSettings, signal: AbortSignal) => Promise<void>	–	Send a test alert to the enabled channels. Without it the send is simulated.
className	string	–	Extra class on the card.

Keyboard interactions

Keys	Action
Arrow keys	On the threshold slider, move the alert line by 1%.
Shift + Arrow keys	Move the alert line by 10%.
PageUp / PageDown	Jump to the next or previous marker.
Home / End	Set the threshold to 10% or 100%.
ArrowUp / ArrowDown	In the budget field, change the budget by 100 (Shift for 1,000).
Space	Toggle a focused channel or the hard stop switch.

Accessibility

• The threshold is a role="slider" labelled "Alert at" with aria-valuetext giving the percent and the amount.
• The budget field is labelled and described by its helper line, which also carries the invalid and over-budget messages with aria-invalid.
• Each channel switch has its own label; the hard stop switch is labelled by its row title.
• Save and test results land in a polite live region, including "Simulated, nothing was sent" when no handler is wired.
• Status is never color alone: every tone pairs an icon with a short label.

Motion

• Spend and forecast fills grow in once when the card scrolls into view (720ms ease-out), then follow budget changes in 160ms.
• The thumb follows the pointer 1:1 while dragging and glides 160ms on clicks, marker jumps and keys.
• Status, helper and footer lines swap with a single crossfade in one grid cell, so nothing changes size.
• Switching Slack off crossfades the preview to a placeholder inside the same box. A test send washes the preview once.
• Reduced motion keeps every end state and drops the fill growth and glides.

Responsive behavior

• Holds from 360px to 580px. Under 440px the gutter tightens, channel destinations move under their names and the footer actions go full width.
• Every line truncates with an ellipsis rather than wrapping, so state changes never change the card height.
• The slider rail is 28px tall for touch and keeps vertical page scroll (touch-action: pan-y).

Performance

• Bar fills animate clip-path and the thumb animates left on one element; no layout animation on text.
• One IntersectionObserver runs until the first reveal, then disconnects.

Notes for AI

• Use for usage-based billing settings: AI model spend, cloud cost budgets, API overage alerts.
• Pass spend and period from your usage API; forecast is derived unless you pass your own.
• Wire onSave and onSendTest with the AbortSignal; the card handles loading, success, error and dirty states.
• Keep it as one card in a settings page; do not wrap it in another card.

Related

• Usage forecast: A billing period usage chart with a forecast cone and a draggable budget that dates the crossing.
• Usage billing: A usage based billing dashboard with a projected spend line, meters against limits, alerts, and an upgrade that morphs into a confirm sheet.
• Billing overview: A billing page where the plan card morphs into a picker and usage, invoices, and card follow.
• Switch: A tactile toggle for settings that take effect immediately.
• Slider: Pick a value or a range on a track that follows your finger.

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