PixelStatCard

Compact metric card surfacing a label, value, optional icon and trend line for dashboards and KPI grids.

  • Seven tone presets aligned with the pxlkit palette (green, cyan, gold, red, purple, pink, neutral).
  • Three sizes (sm/md/lg) that scale padding, value, label and trend typography in lockstep.
  • Icon position aware: top, left, right or bottom-left layouts without prop drilling.
  • Surface-aware (pixel vs linear) — follows the nearest PxlKitSurfaceProvider or a per-card override.
  • Pure presentational + SSR-safe — no client state, fully tree-shakable.
Status
stable
Category
cards
Since
v1.0.0

API

import { PixelStatCard } from '@pxlkit/ui-kit';
PropTypeDefaultDescription
label (required)string—Caption rendered above the value.
value (required)string—Primary metric value.
iconReact.ReactNode—Optional leading icon.
tone'green' | 'cyan' | 'gold' | 'red' | 'purple' | 'pink' | 'neutral''gold'Tone tint for border, soft background, and icon color.
trendstring—Optional trend/delta line rendered under the value.
surface'pixel' | 'linear'—Visual surface override.
size'sm' | 'md' | 'lg''md'Padding + typography scale. Defaults to 'md'.
iconPosition'left' | 'right' | 'top' | 'bottom-left''top'Icon placement relative to label/value. Defaults to 'top'.
valueTonebooleanfalseColor the value with the tone color instead of the default text color.
align'start' | 'center''start'Horizontal alignment of label/value/trend. Defaults to 'start'.
borderedbooleantrueRender with surface-aware border + radius chrome. Defaults to true — a stat card needs visible chrome.

Accessibility

WCAG target: 2.1 AA

  • none

Presentational card with no interactive affordances; relies on surrounding heading hierarchy and tone contrast tokens for legibility.

Usage

import { PixelStatCard } from '@pxlkit/ui-kit';

export function Default() {
  return <PixelStatCard label="Revenue" value="$12,480" trend="+8.2% vs last week" />
}

Examples

Default

import { PixelStatCard } from '@pxlkit/ui-kit';

export function Default() {
  return <PixelStatCard label="Revenue" value="$12,480" trend="+8.2% vs last week" />
}

Tones

import { PixelStatCard } from '@pxlkit/ui-kit';

export function Tones() {
  return (
    <div className="grid grid-cols-2 gap-3">
      <PixelStatCard label="Active" value="1,204" tone="green" trend="+3.1%" />
      <PixelStatCard label="Pending" value="48" tone="gold" trend="2 overdue" />
      <PixelStatCard label="Cancelled" value="12" tone="red" trend="-1 vs ayer" />
      <PixelStatCard label="Sessions" value="3.2k" tone="cyan" trend="+220 hoy" />
      <PixelStatCard label="Members" value="89" tone="purple" />
      <PixelStatCard label="Likes" value="412" tone="pink" />
      <PixelStatCard label="Drafts" value="7" tone="neutral" />
    </div>
  )
}

Sizes

import { PixelStatCard } from '@pxlkit/ui-kit';

export function Sizes() {
  return (
    <div className="flex flex-col gap-3">
      <PixelStatCard label="Small" value="$1,200" size="sm" trend="+2%" tone="cyan" />
      <PixelStatCard label="Medium" value="$8,400" size="md" trend="+5%" tone="gold" />
      <PixelStatCard label="Large" value="$24,900" size="lg" trend="+11%" tone="green" />
    </div>
  )
}

Surfaces

import { PixelStatCard } from '@pxlkit/ui-kit';

export function Surfaces() {
  return (
    <div className="grid grid-cols-2 gap-3">
      <PixelStatCard label="Pixel" value="$4,200" surface="pixel" tone="gold" trend="+6%" />
      <PixelStatCard label="Linear" value="$4,200" surface="linear" tone="gold" trend="+6%" />
    </div>
  )
}

Icon positions

import { PixelStatCard } from '@pxlkit/ui-kit';

export function IconPositions() {
  const dot = <span aria-hidden="true">$</span>
  return (
    <div className="grid grid-cols-2 gap-3">
      <PixelStatCard label="Top" value="$1,200" icon={dot} iconPosition="top" tone="cyan" />
      <PixelStatCard label="Left" value="$1,200" icon={dot} iconPosition="left" tone="green" />
      <PixelStatCard label="Right" value="$1,200" icon={dot} iconPosition="right" tone="purple" />
      <PixelStatCard
        label="Bottom-left"
        value="$1,200"
        icon={dot}
        iconPosition="bottom-left"
        tone="gold"
      />
    </div>
  )
}

Without trend

import { PixelStatCard } from '@pxlkit/ui-kit';

export function WithoutTrend() {
  return <PixelStatCard label="Total users" value="12,480" tone="cyan" />
}

Toned value (centered)

import { PixelStatCard } from '@pxlkit/ui-kit';

export function TonedValueCentered() {
  return (
    <div className="grid grid-cols-2 gap-3">
      <PixelStatCard label="Uptime" value="99.98%" tone="green" valueTone align="center" />
      <PixelStatCard label="Error rate" value="0.02%" tone="red" valueTone align="center" />
    </div>
  )
}

Related