@dax-ui/kpi-card
v0.5.0
Published
dax-ui KpiCard: animated dashboard figures with trends, sparklines and split bars
Maintainers
Readme
@dax-ui/kpi-card
Dashboard figures that animate: the number counts up, cards slide in one after another,
sparklines draw themselves, and split bars grow into place. Six looks (glass, solid,
elevated, tinted, outlined, accent) in five colors. Every motion is off for
viewers who ask for reduced motion.
Installation
pnpm add @dax-ui/kpi-cardMUI and Emotion are included; the app only needs React 18 or 19.
One-time setup per app (skip if the app already uses dax-ui): install
@dax-ui/theme and wrap the app in its UIProvider.
pnpm add @dax-ui/themeUsage
import { formatDuration, formatShare, KpiCard, KpiCardGrid, KpiSplitBar } from '@dax-ui/kpi-card';
import { Clock, Phone, PhoneCall } from 'lucide-react';
<KpiCardGrid>
{/* The headline figure: solid, with the whole split into its parts. */}
<KpiCard variant="solid" label="Total Calls" value={3482} icon={<Phone />} sparkline={lastTenDays}>
<KpiSplitBar
segments={[
{ label: 'AI Calls', value: 2190 },
{ label: 'Manual Calls', value: 1292 },
]}
/>
</KpiCard>
<KpiCard
label="Connected Calls"
value={1874}
icon={<PhoneCall />}
trend={{ value: '12%', direction: 'up' }}
tag={formatShare(1874, 3482)}
tagTone="success"
caption="of total calls"
sparkline={lastTenDays}
/>
<KpiCard variant="accent" color="warning" label="Total Talk Time" value={93420} format={formatDuration} icon={<Clock />} />
</KpiCardGrid>Variants
| variant | Look | On hover |
| --- | --- | --- |
| glass (default) | Frosted and translucent; blurs what's behind it | |
| solid | Filled with color, white text. For the headline figure | |
| elevated | Plain surface with a box shadow | Lifts, shadow deepens |
| tinted | Background washed with color | Wash deepens |
| outlined | Thin border, no shadow | Border takes color |
| accent | Plain surface with a color line along the top that draws in | Line thickens |
color is brand, success, warning, error or info, and also recolors the figure,
icon and sparkline.
Changing figures
When value changes, the figure counts from the old number to the new one rather than
from zero, so a date filter nudges the cards. While data loads, pass loading: the
figure holds and pulses, the trend and tag fade out, and any KpiSplitBar empties.
Screen readers get the final figure once, not every frame.
Formatting
format turns the figure into text on every frame. formatCount (the default) adds
thousands separators; formatDuration turns seconds into two units with the second one
smaller (25h 57m); formatShare(part, whole) gives a percentage for a tag. For
fractional figures, set decimals so the count-up keeps them:
<KpiCard label="Connection Rate" value={54.3} decimals={1} format={(v) => `${v.toFixed(1)}%`} />useCountUp(value, options) and KpiSparkline are exported for building your own cards.
Props
KpiCard
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label (required) | ReactNode | | What the figure measures, e.g. "Connected Calls". |
| value (required) | number | | The figure. Counted up to on mount, and from the old figure to the new one when it changes. |
| animate | boolean | true | Animates the card: it slides in, the figure counts up and the sparkline draws itself. Always off for viewers who ask for reduced motion. |
| caption | ReactNode | | Muted text after the tag, e.g. "of total calls". |
| children | ReactNode | | Extra content under the figure, e.g. a KpiSplitBar. Replaces the footer unless tag or caption is set. |
| color | "brand" \| "success" \| "warning" \| "error" \| "info" | brand | The card's color: the figure, icon, sparkline, and the fill, tint or line of the solid, tinted and accent variants. |
| countUpDuration | number | 900 | How long the count-up takes, in ms. |
| decimals | number | 0 | Decimal places the count-up keeps, for fractional figures like rates. |
| enterDelay | number | | Delay before the card slides in, in ms. Inside a KpiCardGrid it defaults to the card's position times the grid's stagger. |
| format | ((value: number) => KpiDisplayValue) | formatCount | Turns the figure (including every in-between value while counting) into what the card shows. Return { value, unit } to show a smaller unit, e.g. formatDuration. |
| icon | ReactNode | | Icon shown in the tile at the top right, e.g. <PhoneIcon />. Sized to 17px. |
| loading | boolean | false | The figure is not known yet: it holds and pulses, and the trend and tag are hidden. |
| showSparkline | boolean | true | Shows the sparkline. When hidden, the space reserved for it at the bottom goes too. |
| showTag | boolean | true | Shows tag, the pill in the footer (e.g. a share like "42.1%"). The caption stays. |
| showTrend | boolean | true | Shows trend, the change percentage beside the figure. Set false to hide it without removing the data. |
| sparkline | number[] | | Values for a faint line along the bottom of the card, oldest first. Two or more points. |
| tag | ReactNode | | Small pill in the footer, e.g. a share: "42.1%". |
| tagTone | "brand" \| "success" \| "warning" \| "error" \| "info" | brand | Color of the tag pill. |
| trend | KpiTrend | | Change against a previous period, shown beside the figure with an arrow. |
| variant | "glass" \| "solid" \| "elevated" \| "tinted" \| "outlined" \| "accent" | glass | The card's look: glass, solid, elevated, tinted, outlined or accent. |
KpiCardGrid
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | ReactNode | | The cards. |
| columns | number \| Partial<Record<"xs" \| "sm" \| "md" \| "lg" \| "xl", number>> | { xs: 1, sm: 2, xl: 4 } | Cards per row, at each breakpoint. |
| stagger | number | 60 | Delay between one card sliding in and the next, in ms. 0 brings them in together. |
KpiSplitBar
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| segments (required) | KpiSplitBarSegment[] | | The parts of the whole, in order. |
| format | ((value: number) => string) | formatCount | Formats each segment's value in the legend. |
