Awesome KPI Leaderboard

Enterprise-grade KPI Leaderboard component for React with smart health scoring, anomaly detection, theming, filtering, and performance optimizations.

Features

• Smart KPI Health Engine (achievement, status, trend, health score)
• Anomaly detection based on historical deviation
• Ranking and rank movement indicators
• Trend sparkline and trend direction
• Contribution percent
• Filtering (text + numeric) and status filter
• Column reordering and resizing with drag and drop
• Themes: Light, Dark, Purple
• Performance optimizations with memoization and optional virtualization

Installation

npm install awesome-kpi-leader-board

Basic Usage

import { AwesomeLeaderboard } from "awesome-kpi-leader-board";

export default function App() {
  return (
    <AwesomeLeaderboard
      data={[]}
      title="Enterprise KPI Leaderboard"
      subtitle="Regional revenue performance"
      theme="light"
      showTrend
      showContribution
      showVariance
      showRankMovement
    />
  );
}

Examples

No CSS import needed — styles are injected automatically.

Example 1 — Dark theme with sample data

import { AwesomeLeaderboard } from "awesome-kpi-leader-board";
import { data } from "awesome-kpi-leader-board/sample_data";

export default function App() {
  return (
    <AwesomeLeaderboard
      data={data}
      title="Global KPI Leaderboard"
      subtitle="Quarterly performance"
      theme="dark"
      showTrend
      showContribution
      showVariance
      showRankMovement
    />
  );
}

Example 2 — Bottom view with limited rows

import { AwesomeLeaderboard } from "awesome-kpi-leader-board";
import { data } from "awesome-kpi-leader-board/sample_data";

export default function App() {
  return (
    <AwesomeLeaderboard
      data={data}
      title="Bottom Performers"
      subtitle="Areas needing attention"
      view="bottom"
      maxRows={8}
      virtualize
      listHeight={420}
      showTrend={false}
    />
  );
}

Example 3 — Custom health thresholds

import { AwesomeLeaderboard } from "awesome-kpi-leader-board";
import { data } from "awesome-kpi-leader-board/sample_data";

export default function App() {
  return (
    <AwesomeLeaderboard
      data={data}
      title="KPI Health Deep Dive"
      subtitle="Custom thresholds"
      achievementThresholds={{ excellent: 115, onTrack: 95, warning: 75 }}
      showTrend
      showContribution={false}
      showVariance
    />
  );
}

Props

| Prop | Type | Default | Description | | ----------------------- | --------------------------------- | ----------------------------------- | ------------------------------------------------------- | | data | Array<object> | [] | Static dataset. | | dataUrl | string | "" | URL to JSON file (expects { data: [] } or raw array). | | apiEndpoint | string | "" | API endpoint returning JSON data. | | title | string | "KPI Leaderboard" | Header title. | | subtitle | string | "Enterprise performance snapshot" | Header subtitle. | | theme | "light" \| "dark" \| "purple" | "light" | Theme selection. | | maxRows | number \| null | null | Max rows to display. null shows all. | | sortBy | string | "rank" | Reserved (sorting removed from UI). | | sortDirection | "asc" \| "desc" | "asc" | Reserved (sorting removed from UI). | | showTrend | boolean | true | Show trend sparkline. | | showContribution | boolean | true | Show contribution percent. | | showVariance | boolean | true | Show variance percent. | | showRankMovement | boolean | true | Show movement arrow. | | highlightTop | number | 3 | Highlight top N rows. | | onRowClick | (row) => void | undefined | Row click callback. | | locale | string | "en-US" | Locale for number formatting. | | currency | string | "USD" | Currency code for formatting. | | view | "top" \| "bottom" | "top" | Initial list view. | | rowHeight | number | 72 | Row height for virtualization. | | virtualize | boolean | true | Enable virtualization when maxRows is set. | | listHeight | number | 520 | Max list height. | | achievementThresholds | { excellent, onTrack, warning } | {110, 90, 70} | Achievement thresholds for status. | | varianceThresholds | { green, amber } | {5, -5} | Reserved (legacy). |

Smart KPI Health Engine

Achievement

achievement = (metricValue / target) * 100;

Status

if (achievement >= 110) status = "Excellent";
else if (achievement >= 90) status = "On Track";
else if (achievement >= 70) status = "Warning";
else status = "Critical";

Trend Direction

const last = trendData[trendData.length - 1];
const prev = trendData[trendData.length - 2];

trendDirection = last > prev ? "up" : last < prev ? "down" : "stable";

Health Score

healthScore =
  achievement * 0.7 +
  (trendDirection === "up" ? 30 : trendDirection === "down" ? -30 : 0);

Health RAG

if (healthScore >= 90) healthRag = "green";
else if (healthScore >= 70) healthRag = "amber";
else healthRag = "red";

Anomaly Detection

const avg = trendData.reduce((a, b) => a + b, 0) / trendData.length;
const deviation = Math.abs(metricValue - avg) / avg;
const anomaly = deviation > 0.35;

The implementation only flags anomalies when:

• Sudden drop vs average
• Trend direction is down
• Achievement is below 90%

Tooltip

If anomaly is detected, a red tooltip appears:

⚠ Anomaly Detected
Sudden drop of x% vs historical average

Data Structure

{
  id: "RET001",
  entityName: "Mumbai Store",
  metricValue: 1250000,
  target: 1100000,
  previousRank: 2,
  trendData: [980000,1050000,1100000,1180000,1250000]
}

Performance

• useMemo for derived datasets
• useCallback for stable handlers
• Row virtualization for large datasets

Notes

• Ranking is computed automatically from metricValue (desc).
• Rank movement uses previousRank if provided.
• Column resizing and reordering are enabled by drag interactions.