Usage level

Pro

How close a usage is to its limit, on the lines UsageMeters, UsageGlance, UsageRing and PortfolioCard all use, so no two of them disagree: the ratio of what's used to the limit, the level (warning from 75 %, danger from 90 %) and the level's colours. With no limit (null, or 0) there is nothing to read the figure against, so the ratio, the level and the tone are all null: nothing is drawn against a made-up cap. The same when the figure or the limit isn't a finite number. It reads the measured used only: an estimate, pending usage or a may-exceed figure never moves the level.

Safe to call on the server.

const { level, tone } = usageLevel({ used: 8.2, limit: 10 }) // "warning", { token: "cd-warning", … }

Markdown

Version 5.4.0· other versions

This page is for 5.4.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

5.3.0

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.2.0, 4.3.0, 4.4.0, 4.5.0, 5.0.0, 5.1.0 and 5.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

It's types and helpers, listed below.

Install

With the Candor CLI

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

Brings in: ops, tokens

Functions

usageLevel(usage: Pick<Usage, "used" | "limit">)

Values

usageLevelThresholds

The share of the limit at which a usage reaches each level.

{
  readonly warning: 0.75;
  readonly danger: 0.9;
}

usageLevelTones

Each level's colours.

Record<UsageLevelName, UsageLevelTone>

Types

UsageLevelName: How close a usage is to its limit: under 75 % normal, from 75 % warning, from 90 % danger.; "normal" | "warning" | "danger"
UsageLevelTone: A level's colours, as UsageMeters draws them.; { /** The theme variable that fills the used part of a bar or ring: `primary`, `cd-warning` or `destructive`. Read it as `var(--${token})`. */ token: "primary" | "cd-warning" | "destructive"; /** The class for words in the level's colour, readable on the card. */ text: "text-accent-text" | "text-warning-text" | "text-destructive-text"; }
UsageLevel: What `usageLevel` works out from a usage and its limit.; { /** What is used over the limit (1 is at the limit, above 1 past it); null when there is no limit to read it against. */ ratio: number | null; /** The level from the ratio; null when there is no limit. */ level: UsageLevelName | null; /** The level's colours; null when there is no limit, so nothing is drawn in a level's colour. */ tone: UsageLevelTone | null; }

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; }