Usage glance

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/usage-glance

Brings in: bidi, link, locale, motion, ops, tokens, usage-level, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import { UsageGlance } from "@/components/candor/usage-glance"
import { TopBar } from "@/components/candor/top-bar"

export default function Example() {
  return (
    <div className="flex w-full flex-col gap-4">
      {/* In a top bar's end: the label links to the page with the detail (UsageMeters, UsageRing). */}
      <TopBar
        className="rounded-xl border"
        end={<UsageGlance usage={{ label: "Agent spend", used: 4.1, limit: 10, unit: "USD", usedText: "$4.10", limitText: "$10" }} period="November" href="#usage" />}
      />
      {/* From 75 % of the limit the level is said in words with an icon, not by colour alone. */}
      <UsageGlance usage={{ label: "Agent spend", used: 9.3, limit: 10, unit: "USD", usedText: "$9.30", limitText: "$10" }} period="November" />
      {/* Paused is your statement, with your reason: the glance never infers it from what's used. */}
      <UsageGlance usage={{ label: "Agent spend", used: 10, limit: 10, unit: "USD", usedText: "$10", limitText: "$10" }} period="November" paused="Agents stop at the limit" />
      {/* No limit: the count alone, no bar. */}
      <UsageGlance usage={{ label: "Agent runs", used: 412, limit: null, unit: "runs" }} period="this week" />
      {/* Not reported yet: said, never shown as zero. */}
      <UsageGlance usage={{ label: "Agent spend", used: 0, limit: 10, unit: "USD", limitText: "$10" }} period="November" unknown />
    </div>
  )
}

<UsageGlance>

Strings

Motion

Set with --cd-motion-usage-glance-<moment>-* in your brand file; the families are in the design reference.

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

Usage from @/lib/candor/ops

{ label: string; used: number; /** null when there's no limit (the plan sets none). */ limit: number | null; unit: string; resetsAt?: string | undefined; note?: string | undefined; /** * Your own estimate of where it will end, in the same unit (a quote, a forecast), marked on the bar. It is shown as * given and labelled as an estimate; nothing is extrapolated. */ estimate?: number | undefined; /** Words for the estimate marker ("My guess"); defaults to the `usageMeters.estimate` string. */ estimateLabel?: string | undefined; /** * The figures as your server wrote them, shown as they are instead of Candor's number formatting (with the unit * left to you): `used` ("about $4"), `limit` ("$10") and `estimate`. The numbers still place the bar and markers. */ usedText?: string | undefined; limitText?: string | undefined; estimateText?: string | undefined; /** * Work already done that your provider hasn't metered yet, in the same unit: it will count, but isn't in `used`. * Drawn after the used part of the bar, striped, and said in words ("about $1 not yet metered"). */ pending?: number | undefined; /** `pending` as your server wrote it ("about $1"), shown as written. */ pendingText?: string | undefined; /** * How far past the limit this may still go, from your own figure (a provider that checks the limit between steps, a * run already under way), in the same unit. Said under the meter; the meter never works it out. */ mayExceedBy?: number | undefined; /** `mayExceedBy` as your server wrote it, shown as written. */ mayExceedByText?: string | undefined; }