Skip to content
quartiledocsv0.1
GitHub

KPI

PreviewReads selection

A headline number that always states its comparison: a delta, a sparkline, progress toward a target or a two-bar comparison.

Example

Net revenueUSD
$429.8K+4.3%
vs. previous period
Revenue vs. targetUSD
$429.8K/ $450.0K
96% of Q3 targeton pace · 93% expected
Conversion rateRATE
This period3.12%
Previous3.14%
−0.02 pt
// Linked: aggregated over the rows the nearest Selection lets through
<KPI
  label="Net revenue"
  data={orders}
  value="amount"
  compareValue="previous_amount"
  trendBy="date"
  format="currency-compact"
  comparison="vs. previous period"
/>

<KPI
  label="Revenue vs. target"
  data={orders}
  value="amount"
  format="currency-compact"
  target={{ value: 450_000, label: 'Q3 target', expected: 0.93 }}
/>

// Static: plain numbers, no data
<KPI label="Conversion rate" format="percent" unit="RATE" compare={{ current: 0.0312, previous: 0.0314 }} />

Usage

A KPI is static when value is a number, or linked when you pass data and a field: it aggregates the field (sum by default) over the rows the nearest <Selection> lets through. compareValue computes the delta; trendBy draws a sparkline per distinct value; target shows progress and reads “on pace”, “ahead of” or “behind pace” against expected.

Percent-formatted values show their delta in points. deltaDigits chooses 0–20 fractional places for the change pill separately from the value format. Read Formatting and notation for precision and locale choices. KPIGroup lays out up to four KPIs that share data, as cards or as one strip.

Props

KPI

PropTypeDefaultDescription
labelrequiredReactNode—What the number is, e.g. "Net revenue".
valuenumber | null | (keyof R & string)—A number (static mode), or a field of data to aggregate (linked mode). With aggregate="count" the field may be omitted.
dataDataInput<R>—Rows to aggregate. When set, the KPI follows the nearest Selection.
aggregateKPIAggregate<R>—How value is combined across rows. Defaults to sum.
compareValue(keyof R & string) | ((rows: R[]) => number)—Field (or function) giving the comparison value; the delta is computed against it.
trendBykeyof R & string—Draws a sparkline of value aggregated per distinct value of this field, in order.
formatFormatter—Value format. Defaults to the field's format (linked) or "number" (static).
currencystring—ISO 4217 code for currency formats.
unitReactNode—Mono tag in the top-right corner, e.g. "USD". Defaults to the field's unit in linked mode.
deltanumber—The change to show, as a ratio for "percent" (0.046 → +4.6%) or in points for "pt". Computed from compareValue or compare when omitted.
deltaKind'percent' | 'pt'—Defaults to "pt" for percent-formatted values, "percent" otherwise.
deltaDigitsnumber—Delta decimal places, an integer from 0 to 20. Defaults to 1 for percent and 2 for pt.
invertbooleanfalseFor metrics where down is good (churn, cost): flips the delta color.
comparisonReactNode—What the delta is measured against, e.g. "vs. previous 30 days".
trendreadonly number[]—Values for the inline sparkline (static mode, or to override trendBy).
targetKPITarget—Shows progress toward a goal instead of a sparkline.
compareKPICompare | boolean—Two bars, this period against the previous one. Pass the numbers, or true in linked mode to use the aggregated value and compareValue.
loadingbooleanfalseShows a skeleton at the card's size.
selectionstring | false—Selection to read from. Defaults to the nearest; false ignores it.
classNamestring——
styleCSSProperties——
aria-labelstring——

KPIGroup

PropTypeDefaultDescription
dataDataInput<R>—Shared rows for every item that does not bring its own data.
itemsrequiredKPIProps<R>[]—Up to four reads best; the row wraps on narrow screens.
variant'cards' | 'strip''cards'Separate cards, or one strip with hairline dividers.
selectionstring | false—Selection every linked item reads from.
loadingboolean——
classNamestring——
styleCSSProperties——
aria-labelstring——

KPITarget

PropTypeDefaultDescription
valuerequirednumber—The goal, in the same unit as the value.
labelReactNode—Shown after the progress, e.g. "Q3 target".
expectednumber—Share of the target expected by now (0–1), e.g. the share of the period elapsed. Draws a marker on the bar and reads "on pace" within 5 points of it, "ahead of" or "behind pace" otherwise.

KPICompare

PropTypeDefaultDescription
currentrequirednumber——
previousrequirednumber——
currentLabelReactNode——
previousLabelReactNode——

Accessibility

  • Each KPI is a group named by its label, so the value, delta and comparison are read together.
  • While loading it reports aria-busy and keeps its size.
Report an issueBuilt Oct 21, 2026