Skip to Content
BBRICKSv0.7.4
KitPatterns

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

  1. Card: .kit-kpi.kit-kpi--<tone>, flex column, min height 128, padding 16 18, radius 20.
  2. Deco (optional): blob or star at the top inline-end corner, 12% opacity.
  3. Hit button (with onClick): .kit-kpi-hit, covers the card, aria-pressed = active, named by label + value + sub.
  4. Head: .kit-kpi-h, 13px / 600: icon chip .kit-kic (aria-hidden, 15px svg in the tint's ink) + label.
  5. Value: .kit-kpi-v, display 26 / 800, 8px under the head, isolated.
  6. Sub (optional): .kit-kpi-s, 12px / 600.
  7. 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 valueLookWhen to use
tone="lime"--lime-50 / --oliveHealthy / active counts.
tone="rasp"--rasp-50 / --rasp-inkMoney or attention.
tone="butter"--butter / --butter-inkPaused, waiting.
tone="sky"--sky / --sky-inkNeutral info (groups).
tone="lilac"--lilac / --lilac-inkCapacity (seats), messages.
size="default"128px min, 26px valueStandard row.
size="short"No min height, padding 12 16, 22px valueA strip above a list (PR Creators).
deco="blob" | "star"Corner shapeDecoration on one or two cards in a row.
KpiGrid columns={4 | 3 | 2}Cards across4 default; 3 the PR Messages strip; 2 a two-card strip.
KpiGrid phoneColumns={1 | 2}Phone columns2 keeps two across down to 360px.
KpiGrid size="short"All cards shortPR Creators.

States

StateTrigger
Staticno onClick: text only, no button.
ClickableonClick: hover lifts 2px with a shadow; active returns.
Filter onactive={true}: 2px ink outline, aria-pressed="true".
Filter offactive={false}: aria-pressed="false". Navigation cards leave active undefined (no aria-pressed).
Focus-visibleinset focus ring on the hit button.
Progressprogress 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.

PropTypeDefaultDescription
childrenReactNode— (required)The cards.
columns2 | 3 | 44Cards across on a wide screen. 3: the PR Messages strip. 2: a two-card strip at every width down to 600px.
phoneColumns1 | 21Under 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 show progress.
  • Use active only for cards that filter the list below them.

Don't

  • Don't put a button or link in value or sub; only the label may hold a MoneyNote / Term.
  • Don't use more than one deco per two cards.
  • Don't use it for a selectable chart series; use Tile with onSelect.

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-ar raises 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-pressed for 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.

  • 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.

On this page