@ammarkhalidfarooq/dashboard-package

A reusable React Dashboard component library.

Installation

npm install @ammarkhalidfarooq/dashboard-package

Peer dependencies are required in your app:

• react, react-dom
• @mui/material, @mui/icons-material, @emotion/react, @emotion/styled
• apexcharts, react-apexcharts

Usage

Full Dashboard

import React from "react";
import { Dashboard } from "@ammarkhalidfarooq/dashboard-package";

const App = () => {
  return <Dashboard />;
};

export default App;

RenderChartCard (tree-shakeable)

Import only the chart card bundle — avoids pulling in the full dashboard:

import RenderChartCard from "@ammarkhalidfarooq/dashboard-package/RenderChartCard";

Or import from the main entry:

import { RenderChartCard } from "@ammarkhalidfarooq/dashboard-package";

Example:

import { useState } from "react";
import Grid from "@mui/material/Grid";
import RenderChartCard from "@ammarkhalidfarooq/dashboard-package/RenderChartCard";

const chartItem = {
  label: "Revenue per Visitor",
  value: "$5.12",
  subtitle: "Last 30 days · daily aggregation",
  trend: "18% vs last month",
  data: [3000, 4500, 4200, 5800, 5200, 7100, 8500, 9200, 5000],
  categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep"],
};

const App = () => {
  const [metric, setMetric] = useState("Revenue");

  return (
    <Grid container spacing={3}>
      <RenderChartCard
        item={chartItem}
        index={0}
        isPremium
        md={6}
        metric={metric}
        setMetric={setMetric}
      />
    </Grid>
  );
};

export default App;

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | item | object | — | Chart config (see below) | | index | number | — | Unique index for the chart | | isPrimary | boolean | false | Uses a taller chart area | | isPremium | boolean | false | Premium card layout with trend badge | | metric | string | — | Active metric label (e.g. "Revenue") | | setMetric | function | — | Metric change handler | | md | number | 4 | Grid column width on md breakpoint | | type | string | "area" | Chart type ("area", "bar", "donut", etc.) | | sx | object | {} | MUI sx overrides for the grid item wrapper | | cardSx | object | {} | MUI sx overrides for the card container | | contentSx | object | {} | MUI sx overrides for the card content area |

item shape (common fields):

{
  label: "Revenue per Visitor",       // Card title
  value: "$5.12",                     // Main metric value
  subtitle: "Last 30 days",           // Optional subtitle (premium layout)
  trend: "18% vs last month",         // Optional trend badge (premium layout)
  data: [3000, 4500, 4200],           // Single-series chart data
  categories: ["Jan", "Feb", "Mar"],  // X-axis labels
  series: [{ name: "Paid Ads", data: [...] }], // Multi-series (optional)
  stacked: false,                     // Stack series (optional)
  showSelector: false,                // Show metric dropdown (optional)
  hideControls: false,                // Hide menu / show legend only (optional)
  height: 250,                        // Chart height override (optional)
  type: "area",                       // Per-card chart type override (optional)
  colors: ["#6366F1", "#10B981"],     // Custom chart colors (optional)
  footer: { left: "Total", right: "$12k" }, // Optional footer row
}

ActiveCampaignsCard (tree-shakeable)

A configurable table card — used for channel performance, active campaigns, and similar ranked lists.

import ActiveCampaignsCard from "@ammarkhalidfarooq/dashboard-package/ActiveCampaignsCard";

Or import from the main entry:

import { ActiveCampaignsCard } from "@ammarkhalidfarooq/dashboard-package";

Channel performance example:

import ActiveCampaignsCard from "@ammarkhalidfarooq/dashboard-package/ActiveCampaignsCard";

const channelRows = [
  {
    id: "M",
    avatarBg: "#4267B2",
    name: "Meta Ads",
    val1: "$32,800",
    val2: "$112,400",
    val3: "3.4x",
    val4: "$340",
    type: "trend",
    trendType: "up",
    trendLabel: "Improving",
    highlightVal3: true,
    val3Color: "#22C55E",
  },
  {
    id: "G",
    avatarBg: "#4285F4",
    name: "Google Ads",
    val1: "$28,200",
    val2: "$78,300",
    val3: "2.8x",
    val4: "$385",
    type: "trend",
    trendType: "up",
    trendLabel: "Improving",
    highlightVal3: true,
    val3Color: "#22C55E",
  },
];

const App = () => (
  <ActiveCampaignsCard
    title="Channel performance"
    subtitle="Ad platforms ranked by ROAS"
    columns={["channel", "spend", "revenue", "ROAS", "CPA", "trend"]}
    gridTemplateColumns="2.2fr 1fr 1fr 0.8fr 0.8fr 1.2fr"
    height="100%"
    rows={channelRows}
  />
);

export default App;

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | "Active campaigns" | Card title | | subtitle | string | "Live fundraisers ranked by velocity" | Card subtitle | | actionLabel | string | — | Optional top-right action link text | | columns | string[] | ["Campaign", "Raised", "Progress", "Donors", "Avg gift"] | Table header labels | | rows | object[] | [] | Table row data (see below) | | gridTemplateColumns | string | "3fr 1fr 1.5fr 0.8fr 1fr" | CSS grid column template | | height | string | — | Card height (e.g. "100%") | | compact | boolean | false | Smaller typography and spacing | | sx | object | {} | MUI sx overrides for the root card container | | headerSx | object | {} | MUI sx overrides for the title / subtitle header row | | tableSx | object | {} | MUI sx overrides for the scrollable table area |

row shape:

// Channel performance / trend table (6 columns)
{
  id: "M",                    // Avatar label (optional)
  avatarBg: "#4267B2",        // Avatar background color
  name: "Meta Ads",           // Row label
  val1: "$32,800",            // Column 2 (spend / raised)
  val2: "$112,400",           // Column 3 when type !== "progress"
  val3: "3.4x",               // Column 4 (ROAS / donors)
  val4: "$340",               // Column 5 (CPA / avg gift)
  type: "trend",              // "trend" | "progress" — controls column 3 & 6
  trendType: "up",            // "up" | "down" (when type is "trend")
  trendLabel: "Improving",    // Trend badge text
  highlightVal3: true,        // Highlight column 4 value
  val3Color: "#22C55E",       // Highlight color for column 4
}

// Campaign progress table (5 columns)
{
  id: "1",
  name: "Ramadan Appeal",
  val1: "$45,200",
  type: "progress",
  progress: 72,
  progressColor: "rgb(99, 99, 230)",
  val3: "1,240",
  val4: "$36.45",
  status: "Live",
  statusBg: "#DCFCE7",
  statusColor: "#166534",
}

MetricCard (tree-shakeable)

A compact KPI card with icon, value, and caption — used for selectable overview metrics.

import MetricCard from "@ammarkhalidfarooq/dashboard-package/MetricCard";

Or import from the main entry:

import { MetricCard } from "@ammarkhalidfarooq/dashboard-package";

Example:

import { useState } from "react";
import { PaidOutlined as DollarIcon } from "@mui/icons-material";
import MetricCard from "@ammarkhalidfarooq/dashboard-package/MetricCard";

const App = () => {
  const [active, setActive] = useState("Total Raised");

  return (
    <MetricCard
      title="Total Raised"
      value="$124,500"
      caption="12.4% vs last month"
      icon={<DollarIcon />}
      active={active === "Total Raised"}
      onClick={() => setActive("Total Raised")}
    />
  );
};

export default App;

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | — | Card label | | value | string | — | Main metric value | | caption | string | — | Subtitle / trend text below the value | | icon | ReactNode | — | Icon shown in the top-right avatar | | active | boolean | false | Highlights the card as selected | | warning | boolean | false | Warning border and icon styling | | error | boolean | false | Error border and caption styling | | onClick | function | — | Click handler (e.g. select metric) | | sx | object | {} | MUI sx overrides for the root card container | | titleSx | object | {} | MUI sx overrides for the title text | | valueSx | object | {} | MUI sx overrides for the main value text | | captionSx | object | {} | MUI sx overrides for the caption text | | avatarSx | object | {} | MUI sx overrides for the icon avatar |

Development

To preview the component locally:

npm run dev

To build the package:

npm run build

The build outputs ESM and CommonJS bundles in the dist folder, including separate RenderChartCard, ActiveCampaignsCard, and MetricCard bundles for tree-shaking.