Skip to content

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.

TSX · spend-at-a-glance.tsx
"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

With the candor-ui CLI

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 level from the same source as your budget alerts, so the colour and your notifications agree.