KpiCard
The v3 mock's .kpi stat card: an icon chip and label, the value (Jakarta 26/800), the sub line and an optional progress bar on a soft tone, radius 20; size="short" is the mock's shorter .kpis.short card, and icon takes a kit icon name or any element (a <PrIcon>). A clickable card is a plain box with a real button laid over it (.kit-kpi-hit, named by the label, value and sub line, as Tile's), so the label can hold its own "?" (a <MoneyNote> or <Term>) without nesting one button in another; active marks an applied filter (aria-pressed).
import { KpiCard } from '@ergasti/bricks';Examples
Filter cards
A clickable card toggles a filter (active); progress draws a bar; deco adds the corner shape.
Code
import { useState } from 'react';
import { KpiCard, KpiGrid } from '@ergasti/bricks';
function Filters() {
const [chip, setChip] = useState<'all' | 'active' | 'paused'>('all');
return (
<KpiGrid>
<KpiCard tone="lime" icon="user" label="Active" value="301" sub="In your program now" active={chip === 'active'} onClick={() => setChip(chip === 'active' ? 'all' : 'active')} deco="blob" />
<KpiCard tone="butter" icon="pause" label="Paused" value="3" sub="Coupons stopped for now" active={chip === 'paused'} onClick={() => setChip(chip === 'paused' ? 'all' : 'paused')} />
<KpiCard tone="sky" icon="creators" label="Groups" value="3" sub="Open the Groups tab" onClick={() => {}} deco="star" />
<KpiCard tone="lilac" icon="seat" label="Seats left" value="79" sub="321 of 400 seats used" progress={80} onClick={() => {}} />
</KpiGrid>
);
}Read-only
Without onClick the card is plain text, not a button.
Code
import { KpiCard, KpiGrid } from '@ergasti/bricks';
function ReadOnly() {
return (
<KpiGrid>
<KpiCard tone="rasp" icon="payments" label="Paid" value="EGP 275K" sub="This month" />
<KpiCard tone="sky" icon="log" label="Pending" value="EGP 96K" sub="Waiting for approval" />
</KpiGrid>
);
}Two across on a phone
A KpiGrid is four across, two below 1100px and one below 600px; phoneColumns={2} keeps two cards across down to 360px, for short cards. Narrow the window under 600px to see it.
Code
import { KpiCard, KpiGrid } from '@ergasti/bricks';
function PhoneColumns() {
return (
<KpiGrid phoneColumns={2}>
<KpiCard tone="lime" icon="user" label="Active" value="301" />
<KpiCard tone="butter" icon="pause" label="Paused" value="3" />
<KpiCard tone="sky" icon="creators" label="Groups" value="3" />
<KpiCard tone="lilac" icon="seat" label="Seats left" value="79" />
</KpiGrid>
);
}Short cards
For a strip above a list (the PR Creators page), give the grid size="short": every card in it loses its minimum height and gets 12 16 padding and a 22px value. KpiCard size="short" is the same card on its own, for one outside such a grid (here, beside a heading). Keep the defaults for a dashboard's main figures.
Code
import { KpiCard, KpiGrid, PrIcon } from '@ergasti/bricks';
function Short() {
return (
<div style={{ display: 'grid', gap: 16 }}>
<KpiGrid size="short">
<KpiCard tone="lime" icon="user" label="Active" value="10" sub="Approved and selling" />
<KpiCard tone="butter" icon="log" label="Pending" value="2" sub="Waiting for PR approval" />
<KpiCard tone="sky" icon={<PrIcon name="tiers" />} label="Elite" value="4" sub="Top tier" />
<KpiCard tone="lilac" icon="creators" label="Customers" value="38" sub="Customer affiliates" />
</KpiGrid>
<div style={{ maxWidth: 240 }}>
<KpiCard size="short" tone="rasp" icon="clock" label="Waiting for you" value="3" sub="Join requests" />
</div>
</div>
);
}Any icon
icon takes a kit icon name or any element, such as a <PrIcon> or your own svg; it is drawn 15px in the card's ink and hidden from screen readers.
Code
import { KpiCard, KpiGrid, PrIcon } from '@ergasti/bricks';
function ElementIcon() {
return (
<KpiGrid>
<KpiCard tone="sky" icon={<PrIcon name="tiers" />} label="Elite" value="4" sub="Top tier" />
<KpiCard tone="lilac" icon={<svg viewBox="0 0 24 24"><path d="M5 12h14M12 5v14" /></svg>} label="New this week" value="12" sub="Joined since Monday" />
</KpiGrid>
);
}Three across
columns={3} draws the PR Messages strip: three cards across at every width down to 600px (a four-card grid drops to two below 1100px), then one per row on a phone. columns={2} does the same with two.
Code
import { KpiCard, KpiGrid } from '@ergasti/bricks';
function Columns() {
return (
<KpiGrid columns={3}>
<KpiCard tone="rasp" icon="mail" label="Messages sent" value="7" sub="Last 30 days" />
<KpiCard tone="lime" icon="eye" label="Opened on average" value="81%" sub="Of creators who got one" progress={81} />
<KpiCard tone="sky" icon="creators" label="Creators reached" value="2,153" sub="Across all messages" />
</KpiGrid>
);
}Two across
columns={2} keeps two cards side by side at every width down to 600px (a pair of wallet figures); under 600px phoneColumns applies.
Code
import { KpiCard, KpiGrid, Money } from '@ergasti/bricks';
function TwoAcross() {
return (
<KpiGrid columns={2}>
<KpiCard tone="lime" icon="wallet" label="To be paid this month" value={<Money value="48200.00" />} sub="34 creators" />
<KpiCard tone="sky" icon="check" label="Paid so far" value={<Money value="112900.00" />} sub="Since 1 Nov" />
</KpiGrid>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses KpiCard. Written in docs/content/components/KpiCard.md; the props above are read from the code, which wins where the two disagree.
A tinted stat card with an icon chip, label, big value, sub line and optional progress bar; use it in a row of four (KpiGrid) above a list, either as a plain figure or as a filter toggle.
It is the v3 mock's .kpi (radius 20, soft tone, Jakarta 26/800 value). On Brand › Creators the four cards (Active, Paused, Groups, Seats left) filter or navigate the list; Coupons has four coupon stats; Motivation › Gifts five (in StatGrid); the PR Portal uses them as colour stat cards and the three-across Messages strip. A clickable card is a plain box with a real button laid over it, so its label can still hold a MoneyNote or Term "?" without nesting buttons.
Anatomy
- Card:
.kit-kpi.kit-kpi--<tone>, flex column, min height 128, padding 16 18, radius 20. - Deco (optional):
bloborstarat the top inline-end corner, 12% opacity. - Hit button (with
onClick):.kit-kpi-hit, covers the card,aria-pressed=active, named by label + value + sub. - Head:
.kit-kpi-h, 13px / 600: icon chip.kit-kic(aria-hidden, 15px svg in the tint's ink) + label. - Value:
.kit-kpi-v, display 26 / 800, 8px under the head, isolated. - Sub (optional):
.kit-kpi-s, 12px / 600. - Progress (optional):
.kit-kpi-bar, 5px white-75% track, 10px under the sub,aria-hidden.
KpiGrid: .kit-kpis, 4 across (14px gap), 2 below 1100px, 1 below 600px.
Variants
| Prop value | Look | When to use |
|---|---|---|
tone="lime" | --lime-50 / --olive | Healthy / active counts. |
tone="rasp" | --rasp-50 / --rasp-ink | Money or attention. |
tone="butter" | --butter / --butter-ink | Paused, waiting. |
tone="sky" | --sky / --sky-ink | Neutral info (groups). |
tone="lilac" | --lilac / --lilac-ink | Capacity (seats), messages. |
size="default" | 128px min, 26px value | Standard row. |
size="short" | No min height, padding 12 16, 22px value | A strip above a list (PR Creators). |
deco="blob" | "star" | Corner shape | Decoration on one or two cards in a row. |
KpiGrid columns={4 | 3 | 2} | Cards across | 4 default; 3 the PR Messages strip; 2 a two-card strip. |
KpiGrid phoneColumns={1 | 2} | Phone columns | 2 keeps two across down to 360px. |
KpiGrid size="short" | All cards short | PR Creators. |
States
| State | Trigger |
|---|---|
| Static | no onClick: text only, no button. |
| Clickable | onClick: hover lifts 2px with a shadow; active returns. |
| Filter on | active={true}: 2px ink outline, aria-pressed="true". |
| Filter off | active={false}: aria-pressed="false". Navigation cards leave active undefined (no aria-pressed). |
| Focus-visible | inset focus ring on the hit button. |
| Progress | progress 0–100, drawn clamped 2–100. |
Types
KpiGrid
KpiGrid is the mock's .kpis row and has no card of its own: use it around every row of KpiCards.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — (required) | The cards. |
columns | 2 | 3 | 4 | 4 | Cards across on a wide screen. 3: the PR Messages strip. 2: a two-card strip at every width down to 600px. |
phoneColumns | 1 | 2 | 1 | Under 600px: 1 stacks; 2 keeps two across down to 360px (Brand › Creators uses 2). |
size | 'default' | 'short' | 'default' | short makes every card in it the .kpis.short card (PR Creators). |
Layout: grid with 14px gaps and 16px under it (0 as a direct child of the shell's main, which spaces it). columns={4} is four across above 1100px, two across from 1100px down to 600px, then phoneColumns. So the mock's four-across row needs a content area wider than 1100px viewport; the preview's lead row is drawn at 1280px for that reason.
Usage
// Brand › Creators › the mock's row (as src/gallery/screens/CreatorsListScreen.tsx draws it)
<KpiGrid phoneColumns={2}>
<KpiCard tone="lime" icon="user" label="Active" value={260} sub="86% of your creators · selling now"
progress={(260 / 304) * 100} active={chip === 'active'} onClick={() => setChip(chip === 'active' ? 'all' : 'active')} />
<KpiCard tone="butter" icon="pause" label="Paused" value={22} sub="Coupons on hold · no new sales"
progress={(22 / 304) * 100} active={chip === 'paused'} onClick={() => setChip(chip === 'paused' ? 'all' : 'paused')} />
<KpiCard tone="lilac" icon="creators" label="Groups" value={3} sub="12 creators in a group"
progress={(12 / 304) * 100} onClick={() => setTab('groups')} />
<KpiCard tone="rasp" icon="seat" label="Seats left" value={79} sub="321 of 400 seats used" progress={(321 / 400) * 100} onClick={openLimit} />
</KpiGrid>
<Card title="My creators">…</Card>// A money figure with its "?" in the label
<KpiCard tone="rasp" icon="coupon" value={<Money value="184300.00" compact />}
label={<MoneyNote figure="coupon_sales">Sales via coupons</MoneyNote>} sub="Last 30 days" onClick={openSales} />// PR Portal › Messages strip
<KpiGrid columns={3}>…three static KpiCards…</KpiGrid>Where it appears
- In the v3 mocks: Brand › Creators › four stat cards (filter / navigate) (BrandCreators); Brand › Coupons › four coupon stat cards (BrandCoupons); Brand › Motivation › Gifts › five stat cards in
StatGrid(BrandMotivation); PR Portal › colour stat cards on Home, Creators (size="short"), Affiliate programs, Gift analytics, Messages (columns={3}) (PrHome, PrCreators, PrPrograms, PrGiftAnalytics).
Guidelines
Do
- Use one row of 3–4 cards; vary tone across the row.
- Say the number's meaning in
sub; always do so when you showprogress. - Use
activeonly for cards that filter the list below them.
Don't
- Don't put a button or link in
valueorsub; only the label may hold aMoneyNote/Term. - Don't use more than one
decoper two cards. - Don't use it for a selectable chart series; use
TilewithonSelect.
RTL and Arabic
- Deco moves to the left corner; head and sub align to the inline start.
- The value is isolated (
unicode-bidi: isolate,dir="ltr"), so "321 / 400" keeps its order; Arabic sub lines like "321 من 400 مكان مستخدم" read RTL. --lh-arraises the value's line height for Arabic.
Tokens
--lime-50, --olive, --rasp-50, --rasp-ink, --butter, --butter-ink, --sky, --sky-ink, --lilac, --lilac-ink, --ink, --rasp, --font-family-display, --lh-ar, --focus-ring-inset.
Accessibility
- Clickable: one real
<button>overlay named by label, value and sub;aria-pressedfor filters. - Icon chip, deco and progress bar are
aria-hidden. - Each tone's ink on its tint meets AA at 12px / 600.
- The whole card is the target (at least 128px tall, or about 102px for
short), so it clears the 44px touch floor at every width.
Found in the source
- ARIA attributes set:
aria-pressed,aria-labelledby,aria-hidden. - Its tests cover: “icon chip + label, value, sub and an optional progress bar (clamped 2–100)”; “a filter card has one button (laid over it) with aria-pressed, named by label and value; click, Enter and Space toggle it”; “Arabic + RTL: the label in Arabic, the value isolated LTR; the grid wraps the cards”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
Tile: the white metric tile with delta and sparkline (Home, Analytics).StatGrid: five-across row for KPI cards.QueueTile(PR): approval queue counters.FilterChips: when filters have no figures.
See also: Deco · Icon · Filters · KpiGrid · PrIcon · Money · Accordion · Card · HeroCard · KeyValue
Source
src/kit/patterns/KpiCard.tsx (line 48) on GitHub.