📊 Retro Dashboard

A flexible and customizable React dashboard builder for creating modern analytics dashboards with charts, KPIs, and filters — built with React, MUI, and Chart.js.

✨ Features

• ⚡️ Plug-and-play dashboard builder
• 📈 Prebuilt chart types — Bar, Line, Pie, Doughnut
• 🧩 Configurable card and chart widgets
• 🎨 MUI-based styling and theme profiles
• 🔄 Automatic data refresh & filtering
• 🌐 Built-in API integration via FeathersJS/REST

📦 Installation

Install via Yarn or npm:

# Using Yarn
yarn add retro-dashboard

# Using npm
npm install retro-dashboard

Required peer dependencies:

yarn add react react-dom chart.js react-chartjs-2

⚙️ Quick Usage Example

Below is a fully working dashboard configuration using DashboardBuilder.

"use client";

import React from "react";
import {
  DashboardBuilder,
  DashboardConfig,
  GlobalFilterConfig,
} from "retro-dashboard";
import { Divider, Typography } from "@mui/material";
import dayjs from "dayjs";
import restApp, { authCookieName } from "../../apis/rest.app";

// Dashboard structure configuration
const dashboardConfig: DashboardConfig = {
  id: "main-dashboard",
  gridSpacing: 2,
  themeProfiles: {
    primary: {
      bg: "linear-gradient(135deg, #e3f2fd 0%, #bbdefb 100%)",
      border: "#90caf9",
    },
    revenue: {
      bg: "#f3e5f5",
      border: "#ce93d8",
    },
    neutral: {
      bg: "#fafafa",
      border: "#e0e0e0",
    },
  },
  rows: [
    {
      id: "row-top",
      widgets: [
        {
          key: "kpi-1",
          type: "card",
          title: "Total Blogs",
          dataKey: "total_blogs",
          themeKey: "primary",
          size: { md: 4 },
          cardProps: {
            icon: "/images/dashboard/total-blogs.svg",
          },
        },
        {
          key: "kpi-2",
          type: "card",
          title: "Total Views",
          dataKey: "total_views",
          themeKey: "revenue",
          size: { md: 4 },
          cardProps: {
            icon: "/images/dashboard/total-views.svg",
          },
        },
        {
          key: "kpi-3",
          type: "card",
          title: "Total Categories",
          dataKey: "total_categories",
          themeKey: "neutral",
          size: { md: 4 },
          cardProps: {
            icon: "/images/dashboard/total-categories.svg",
          },
        },
      ],
    },
    {
      id: "row-charts",
      rowStyle: {
        minHeight: "400px",
      },
      widgets: [
        {
          key: "ticket-sales",
          type: "pie",
          title: "Video vs Normal",
          dataKey: "blog_type_chart",
          dataMapping: {
            labelsKey: "event_name",
            dataKey: "video",
            backgroundColor: ["#48666e", "#aaba63"],
          },
          chartOptions: {
            borderWidth: 5,
            borderColor: "#fff",
            showLegend: true,
          },
          size: { md: 6 },
        },
        {
          key: "bar-sales",
          type: "line",
          title: "Views",
          dataKey: "views_data",
          dataMapping: {
            labelsKey: "interval",
            dataKey: "count",
            backgroundColor: ["#48666e"],
          },
          size: { md: 6 },
        },
      ],
    },
    {
      id: "row-mixed",
      widgets: [
        {
          key: "weekly-sales",
          type: "bar",
          title: "Blogs",
          dataKey: "blog_data",
          dataMapping: {
            labelsKey: "interval",
            dataKey: "count",
            backgroundColor: ["#48666e"],
          },
          size: { md: 12 },
        },
      ],
    },
  ],
};

// Global filters configuration
const filters: GlobalFilterConfig[] = [
  {
    id: "sales_period",
    type: "period",
    payloadKey: "blog_graph_interval_data_filter_type",
    options: [
      {
        value: "last_7_days",
        label: "Last 7 Days",
        formatLable: [
          {
            keys: ["bar-sales", "weekly-sales"],
            modifyLabels: (labels) =>
              labels.map((label) => dayjs(label).format("ddd")),
          },
        ],
      },
      {
        value: "this_month",
        label: "This Month",
        formatLable: [
          {
            keys: ["bar-sales", "weekly-sales"],
            modifyLabels: (labels) => dayjs(label).format("DD")),
          },
        ],
      },
      { value: "custom", label: "Custom", customRange: true },
    ],
  },
];

export default function DashboardPage() {
  return (
    <div style={{ boxSizing: "border-box" }}>
      <Typography sx={{ fontWeight: 600, fontSize: 20 }}>
        Welcome, Admin
      </Typography>
      <Divider sx={{ my: 2 }} />
      <DashboardBuilder
        config={dashboardConfig}
        rowSpacing={1}
        showTitles
        apiEndpoint="v1/admin/admin-dashboard"
        authCookieName={authCookieName}
        restApp={restApp}
        method="POST"
        extraBodyParams={{
          statistics: true,
          blog_type_pie_chart_data: true,
          blog_graph_interval_data: true,
          views_graph_interval_data: true,
        }}
        globalFilterConfig={filters}
        autoRefetchOnFilterChange
        onGlobalFiltersChange={(filters) =>
          console.log("Filters changed:", filters)
        }
      />
    </div>
  );
}

🧩 DashboardBuilder Props

| Prop | Type | Description | | --------------------------- | ---------------------- | -------------------------------------- | | config | DashboardConfig | Dashboard layout and widget setup | | apiEndpoint | string | API endpoint to fetch dashboard data | | restApp | any | Feathers/REST client instance | | authCookieName | string | Cookie name for authentication | | method | "GET" \| "POST" | HTTP method for API calls | | extraBodyParams | object | Extra payload for API requests | | globalFilterConfig | GlobalFilterConfig[] | Global filters configuration | | onGlobalFiltersChange | (filters) => void | Callback triggered on filter changes | | autoRefetchOnFilterChange | boolean | Auto refresh data when filters change | | rowSpacing | number | Grid spacing between dashboard rows | | showTitles | boolean | Show/hide widget titles | | filterBoxStyle | CSSProperties | Custom styles for the filter container |

🧠 Types Overview

• DashboardConfig — defines dashboard rows, widgets, and themes.
• GlobalFilterConfig — defines filter controls and data bindings.

🪄 Supported Widget Types

| Type | Description | | ------------ | ------------------------- | | "card" | KPI or metric card | | "bar" | Bar chart (uses Chart.js) | | "line" | Line chart | | "pie" | Pie chart | | "doughnut" | Doughnut chart |

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgements

• Built with React, MUI, and Chart.js.