awesome-kpi-card

Enterprise-grade KPI Card component for React. Three layout variants (compact, detailed, premium), sparkline, trend arrow, variance badge, RAG status indicator, optional REST data fetching with auto-refresh, and full theming via CSS custom properties — all styles injected at runtime so no CSS import is needed.

Features

3 variants — compact (tight, label + value + variance), detailed (sparkline + variance line), premium (sparkline + target + previous + all indicators)
Trend arrow — ▲ / ▼ / — based on value vs previous, with a configurable dead-zone (trendSensitivity)
Variance badge — +4.50% / −3.20% coloured by direction, shown in header (compact) or value row (detailed/premium)
RAG status — colour-coded dot + label driven by value / target ratio against configurable thresholds
SVG sparkline — polyline chart from history array, with optional animated draw
REST data fetching — endpoint prop + autoRefresh polling; local data prop always takes precedence
transform hook — normalise any remote payload shape before rendering
onClick callback — receives the fully resolved data object
4 built-in themes — dark, light, purple plus the default — all driven by CSS custom properties
Self-contained — styles injected at runtime; no CSS import, no sub-folder dependencies
ESM + CJS dual build — works in Vite, Next.js, CRA, and any modern bundler
Zero runtime dependencies beyond React

Installation

npm install awesome-kpi-card
# or
yarn add awesome-kpi-card
# or
pnpm add awesome-kpi-card

Peer dependencies — React ≥ 17 and ReactDOM ≥ 17 must already be installed.

Quick Start

No CSS import needed — styles are injected automatically on first render.

import AwesomeKpiCard from 'awesome-kpi-card';

export default function App() {
  return (
    <AwesomeKpiCard
      variant="premium"
      data={{
        label:    'Revenue',
        value:    5200000,
        target:   5000000,
        previous: 4800000,
        history:  [4000000, 4200000, 4500000, 4800000, 5200000],
      }}
      format="currency"
      currency="USD"
      thresholds={{ good: 1, warning: 0.85 }}
      animated
    />
  );
}

Both import styles work:

// Default import
import AwesomeKpiCard from 'awesome-kpi-card';

Props

Prop	Type	Default	Description
`variant`	`'compact' \| 'detailed' \| 'premium'`	`'detailed'`	Controls layout, density, and which elements are shown by default.
`label`	`string`	`'KPI Metric'`	KPI title label shown in the card header.
`value`	`number`	`0`	Current KPI value.
`target`	`number`	—	Target value. Used for variance, RAG status, and the target line in premium.
`previous`	`number`	—	Previous period value. Used for the trend arrow direction.
`history`	`number[]`	—	Array of historical values for the sparkline (oldest → newest).
`data`	`object`	—	Local data object with any of `{ label, value, target, previous, history }`. Takes precedence over `endpoint`.
`endpoint`	`string`	—	REST URL to fetch KPI data from. Response root or `.data` key is used.
`method`	`string`	`'GET'`	HTTP method for the `endpoint` request.
`autoRefresh`	`number`	—	Polling interval in ms. Requires `endpoint`.
`transform`	`(normalized, raw) => object`	—	Transforms the remote payload before it is merged into the card's data.
`thresholds`	`{ good: number, warning: number }`	`{ good: 1, warning: 0.85 }`	RAG ratio thresholds. `good` = `value/target ≥ good`, `warning` = ≥ warning.
`format`	`'number' \| 'currency' \| 'percent'`	`'number'`	Value display format.
`currency`	`string`	`'USD'`	ISO currency code for `format="currency"`.
`showSparkline`	`boolean`	variant default	Override sparkline visibility.
`showVariance`	`boolean`	variant default	Override variance badge visibility.
`showTrend`	`boolean`	`true`	Show/hide the trend arrow.
`showTarget`	`boolean`	variant default	Show the target meta line (on by default in `premium`).
`showPrevious`	`boolean`	variant default	Show the previous meta line (on by default in `premium`).
`animated`	`boolean`	`false`	Animate the sparkline draw on mount.
`trendSensitivity`	`number`	`0`	Dead-zone delta — differences ≤ this value show neutral `—` instead of ▲/▼.
`statusLabels`	`{ good?: string, warning?: string, critical?: string }`	—	Override the default RAG status label strings.
`onClick`	`(data) => void`	—	Fired when the card is clicked. Receives the fully resolved data object.
`className`	`string`	—	Additional CSS class on the root `<section>`.
`style`	`object`	—	Inline styles on the root element.

Variant defaults

Feature	`compact`	`detailed`	`premium`
`showSparkline`	`false`	`true`	`true`
`showVariance`	`true`	`true`	`true`
`showTarget`	`false`	`false`	`true`
`showPrevious`	`false`	`false`	`true`

Examples

Example 1 — Three variants side by side

import AwesomeKpiCard from 'awesome-kpi-card';

var kpiData = {
  label:    'Monthly Revenue',
  value:    5200000,
  target:   5000000,
  previous: 4800000,
  history:  [3800000, 4100000, 4400000, 4700000, 4900000, 5200000],
};

var thresholds = { good: 1, warning: 0.9 };

export default function VariantsDemo() {
  return (
    <div style={{ display: 'flex', gap: 20, padding: 32, background: '#10151c', flexWrap: 'wrap' }}>

      <div style={{ width: 260 }}>
        <AwesomeKpiCard
          variant="compact"
          data={kpiData}
          format="currency"
          thresholds={thresholds}
        />
      </div>

      <div style={{ width: 300 }}>
        <AwesomeKpiCard
          variant="detailed"
          data={kpiData}
          format="currency"
          thresholds={thresholds}
          animated
        />
      </div>

      <div style={{ width: 340 }}>
        <AwesomeKpiCard
          variant="premium"
          data={kpiData}
          format="currency"
          thresholds={thresholds}
          animated
        />
      </div>

    </div>
  );
}

Example 2 — Live REST API with auto-refresh and custom status labels

import AwesomeKpiCard from 'awesome-kpi-card';

export default function LiveKpi() {
  return (
    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 280px)', gap: 20, padding: 32, background: '#0a0f16' }}>

      <AwesomeKpiCard
        variant="premium"
        endpoint="/api/kpi/revenue"
        autoRefresh={30000}
        format="currency"
        currency="USD"
        thresholds={{ good: 1, warning: 0.9 }}
        statusLabels={{ good: 'Exceeding', warning: 'Near Miss', critical: 'Behind' }}
        animated
      />

      <AwesomeKpiCard
        variant="detailed"
        endpoint="/api/kpi/nps"
        autoRefresh={60000}
        format="number"
        thresholds={{ good: 0.9, warning: 0.75 }}
        statusLabels={{ good: 'Excellent', warning: 'Acceptable', critical: 'Poor' }}
      />

      <AwesomeKpiCard
        variant="detailed"
        endpoint="/api/kpi/uptime"
        autoRefresh={10000}
        format="percent"
        thresholds={{ good: 0.999, warning: 0.995 }}
        statusLabels={{ good: 'Healthy', warning: 'Degraded', critical: 'Down' }}
      />

    </div>
  );
}

Example 3 — `onClick`, `transform`, and a custom side panel

Demonstrates transforming a non-standard API response and handling card clicks with a detail drawer.

import { useState } from 'react';
import AwesomeKpiCard from 'awesome-kpi-card';

// The API returns: { metric: "...", current: 123, goal: 100, trend: [...] }
// We use `transform` to map it to the expected shape.
function transformApiResponse(normalized) {
  return {
    label:   normalized.metric,
    value:   normalized.current,
    target:  normalized.goal,
    history: normalized.trend,
  };
}

var kpis = [
  { id: 'cac',        label: 'Customer Acq. Cost',  value: 84,      target: 90,      previous: 91,      history: [100, 96, 93, 91, 88, 84],      format: 'currency' },
  { id: 'churn',      label: 'Monthly Churn',        value: 0.021,   target: 0.025,   previous: 0.028,   history: [0.04, 0.035, 0.03, 0.028, 0.025, 0.021], format: 'percent' },
  { id: 'arpu',       label: 'ARPU',                 value: 142,     target: 130,     previous: 128,     history: [110, 118, 124, 128, 135, 142],  format: 'currency' },
  { id: 'activation', label: 'Activation Rate',      value: 0.712,   target: 0.70,    previous: 0.68,    history: [0.61, 0.64, 0.67, 0.68, 0.70, 0.712], format: 'percent' },
];

var drawerStyle = {
  position: 'fixed', top: 0, right: 0, width: 340,
  height: '100vh', background: '#111827',
  borderLeft: '1px solid rgba(255,255,255,0.08)',
  padding: 32, zIndex: 100, color: '#f7f3e8',
  fontFamily: 'sans-serif', overflowY: 'auto',
  display: 'flex', flexDirection: 'column', gap: 16,
};

export default function KpiDashboard() {
  var [selected, setSelected] = useState(null);

  return (
    <div style={{ padding: 32, background: '#0a0f16', minHeight: '100vh' }}>
      <h2 style={{ color: '#f7f3e8', fontFamily: 'sans-serif', marginBottom: 24 }}>Growth Metrics</h2>

      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(260px,1fr))', gap: 20 }}>
        {kpis.map(function(kpi) {
          return (
            <AwesomeKpiCard
              key={kpi.id}
              variant="detailed"
              label={kpi.label}
              value={kpi.value}
              target={kpi.target}
              previous={kpi.previous}
              history={kpi.history}
              format={kpi.format}
              thresholds={{ good: 1, warning: 0.9 }}
              animated
              onClick={function(data) { setSelected({ ...kpi, resolved: data }); }}
            />
          );
        })}
      </div>

      {selected && (
        <div style={drawerStyle}>
          <button
            onClick={function() { setSelected(null); }}
            style={{ alignSelf: 'flex-end', background: 'transparent', border: '1px solid rgba(255,255,255,0.15)', color: '#fff', borderRadius: 4, width: 28, height: 28, cursor: 'pointer' }}
          >✕</button>

          <div style={{ fontSize: 22, fontWeight: 700 }}>{selected.label}</div>
          <div style={{ fontSize: 13, color: 'rgba(247,243,232,0.6)' }}>Format: {selected.format}</div>

          <div style={{ height: 1, background: 'rgba(255,255,255,0.08)' }} />

          <div style={{ display: 'flex', flexDirection: 'column', gap: 8, fontSize: 13 }}>
            <div>Current: <strong>{String(selected.value)}</strong></div>
            <div>Target: <strong>{String(selected.target)}</strong></div>
            <div>Previous: <strong>{String(selected.previous)}</strong></div>
          </div>

          <div style={{ marginTop: 'auto', fontSize: 11, color: 'rgba(255,255,255,0.2)', fontFamily: 'monospace' }}>
            ID: {selected.id}
          </div>
        </div>
      )}
    </div>
  );
}

Theming

All colours are CSS custom properties. Apply a theme class to a wrapper element:

<div class="theme-dark">  <!-- or theme-light / theme-purple -->
  ...
</div>

Or override the variables directly:

:root {
  --kpi-bg:       #0a0f16;
  --kpi-text:     #f7f3e8;
  --kpi-positive: #4cd39b;  /* RAG good / positive variance */
  --kpi-negative: #ff6a6a;  /* RAG critical / negative variance */
  --kpi-warning:  #f1b463;  /* RAG warning */
  --kpi-border:   rgba(255,255,255,0.08);
  --kpi-muted:    rgba(247,243,232,0.7);
  --kpi-panel:    rgba(13,18,26,0.92);
}

The --kpi-accent variable is set automatically per-card to the current RAG colour and drives the card glow.

Built-in theme classes

Class	Background	Accent
(default / dark)	`#10151c`	`#4cd39b` / `#ff6a6a` / `#f1b463`
`.theme-light`	`#f6f6f2`	`#1a9b64` / `#e15656` / `#cf8a3a`
`.theme-dark`	`#0a0f16`	`#4cd39b` / `#ff6a6a` / `#f1b463`
`.theme-purple`	`#1a0d2e`	`#5ee6b8` / `#ff7aa2` / `#f2c264`

License

MIT

awesome-kpi-card

Package Exports

Readme

awesome-kpi-card

Features

Installation

Quick Start

Props

Variant defaults

Examples

Example 1 — Three variants side by side

Example 2 — Live REST API with auto-refresh and custom status labels

Example 3 — onClick, transform, and a custom side panel

Theming

Built-in theme classes

License

Example 3 — `onClick`, `transform`, and a custom side panel