Kpi
KPI card showing a primary metric with optional delta indicator, icon, and sparkline.
Category: chart · WCAG 2.1-AA · chart, kpi, metric, dashboard, data-viz
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | number | — | Primary metric value |
label | string | — | Metric label — rendered visibly at the top of the tile. |
delta | number | — | Change value (positive = up, negative = down) |
deltaFormat | 'number' | 'percent' | ((delta: number) => string) | number | How to render `delta`. `'percent'` treats it as percentage points and appends `%` (25.6 → +25.6%) — it does not multiply by 100. A function owns the whole string, sign included. |
goodDirection | 'up' | 'down' | 'neutral' | up | Which direction is *good* for this metric — the colour, independent of the arrow (which follows the sign of `delta`). 'up' (default) suits revenue; use 'down' for errors, latency, cost or churn, where a rise is bad news; 'neutral' keeps the arrow and drops the sentiment colour. |
deltaLabel | string | — | Delta context label (e.g. "vs last week") |
icon | ReactNode | — | Icon element rendered in the component. |
sparkline | number[] | — | Trend data for embedded sparkline |
className | string | — | Additional CSS class names merged onto the root element. |
Design tokens
--cascivo-chart-1
When to use
- Highlighting a single headline metric with an optional change delta
- Building dashboard summary tiles with an embedded sparkline trend
When not to use
- Showing a value against a target or range — use Bullet or Meter
- Comparing multiple values — use a chart
Examples
Basic KPI card
import { Kpi } from '@cascivo/charts'
<Kpi value="$12,400" label="Monthly revenue" delta={8.2} deltaLabel="vs last month" />