Patterns / Spend at a glance
Spend at a glance: a pill that opens the detail
Money an agent spends should be quiet but always in reach. Put a UsageMeter with variant="pill" in the header: a small ring filling with the share of the budget used, then "$18.82 / $50 · Nov". Within budget the ring is the accent, not green; from 75 % it is drawn in the warning colour and from 90 % in the danger colour, with an icon, and the level is in its words for screen readers, never colour alone.
Give the pill a popover and it becomes a button that opens it. Inside, show the same usage as a bar (with when it resets), the three items that cost most, the rest as one "Others" line, and two worded links: "See all spend" and "Edit budget…". Which period or scope the pill counts (this month, one round of work) is your choice of Usage.
Give the usage a currency and its figures are written as money. When the figure used so far is your own estimate (work on a subscription that reports no cost), set basis: "estimated": the pill shows "est." and its words say "estimated". With no budget the pill says "no cap yet" and draws no ring.
The components
- Usage metersProThe pill in the header, and the same usage as a bar inside the popover.
- MoneyProEach item's cost, and the Others total, written in the locale.
- PopoverFreeWhat the pill opens; the pill names it with the usage's label.
See it working
The code
The pill and its popover: the bar, the top three by cost, Others, and links to all spend and the budget.
"use client"
import { UsageMeter } from "@/components/candor/usage-meters"
import { Money } from "@/components/candor/money"
import type { Usage } from "@/lib/candor/ops"
/** One thing spend went on this period, from your server. `cost` is null while it isn't measured yet. */
type SpendItem = { id: string; name: string; cost: number | null }
export function SpendAtAGlance({ spend, period, items, seeAllHref, budgetHref }: {
/** This period's spend against the budget, with `currency` (and `basis: "estimated"` when it is your estimate). */
spend: Usage
/** The period in your words: "Nov", "Round 2". */
period: string
items: SpendItem[]
seeAllHref: string
budgetHref: string
}) {
// Your figures, sorted here: the three that cost most, then everything else as one "Others" line.
const measured = items.flatMap((item) => (item.cost === null ? [] : [{ ...item, cost: item.cost }]))
const byCost = [...measured].sort((a, b) => b.cost - a.cost)
const topThree = byCost.slice(0, 3)
const rest = byCost.slice(3)
const othersTotal = rest.reduce((sum, item) => sum + item.cost, 0)
// An item whose cost isn't known yet is said, never dropped from the sum without a word.
const notMeasured = items.length - measured.length
return (
<UsageMeter
variant="pill"
surface="header"
usage={spend}
period={period}
popover={
<div className="flex flex-col gap-3">
{/* The same usage as a bar: the figure, its limit and when it resets. */}
<UsageMeter usage={spend} className="border-0 p-0" />
<ul aria-label="Top costs" className="flex flex-col gap-1 text-sm">
{topThree.map((item) => (
<li key={item.id} className="flex justify-between gap-3">
<span className="truncate">{item.name}</span>
<Money amount={item.cost} currency={spend.currency} />
</li>
))}
{rest.length > 0 && (
<li className="flex justify-between gap-3 text-muted-foreground">
<span>Others ({rest.length})</span>
<Money amount={othersTotal} currency={spend.currency} />
</li>
)}
</ul>
{notMeasured > 0 && <p className="text-xs text-muted-foreground">{notMeasured} not measured yet, so not in the list.</p>}
<div className="flex justify-between gap-3 text-sm">
<a href={seeAllHref} className="underline underline-offset-2">See all spend</a>
<a href={budgetHref} className="underline underline-offset-2">Edit budget…</a>
</div>
</div>
}
/>
)
}
Install
Each component brings in what it depends on. The free ones install as they are; Pro and Premium ones need a licence key.
Good to know
- "Others" is the sum of the measured costs after the top three, worked out by your app. When an item's cost isn't known yet, say so under the list; don't drop it from the sum without a word.
- Inside a card that is one link, such as PortfolioCard, the pill is static: use
usageVariant="pill"there and put the detail on the page the card opens. - Pass the pill's
levelfrom the same source as your budget alerts, so the colour and your notifications agree.