Apptimus Dashboard

A React-based draggable dashboard powered by GridStack.js, optimized for Next.js integration.

Features

• 🎯 Five Widget Types: TEXT, NUMBER, CHART, TABLE, and IMAGE
• 🖱️ Drag & Drop: Intuitive drag-and-drop interface for rearranging widgets
• 📱 Responsive: Mobile-friendly layouts with GridStack.js
• 🔧 Customizable: Flexible grid options and widget positioning
• 💾 Persistent: Save and load dashboard layouts
• ⚡ Next.js Ready: SSR compatible with ESM/CJS outputs

Installation

npm install apptimus-dashboard

Peer Dependencies

This package requires the following peer dependencies:

npm install @apptimus-ui/modal@^1.0.0 @apptimus-ui/table@* @apptimus-ui/theme@^1.3.0

Quick Start

import { DraggableDashboard } from 'apptimus-dashboard';
import TextWidget from './TextWidget';

function MyDashboard() {
  const [widgets, setWidgets] = useState([
    {
      id: '1',
      type: 'TEXT',
      x: 0,
      y: 0,
      w: 4,
      h: 2,
      content: <TextWidget text="Dashboard" />
    }
  ]);

  const handleLayoutChange = (layout) => {
    // Save layout to your backend or state
    console.log('Layout changed:', layout);
  };

  return (
    <DraggableDashboard
      widgets={widgets}
      onLayoutChange={handleLayoutChange}
    />
  );
}

Props

DraggableDashboardProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | widgets | DashboardWidget[] | Yes | Array of widgets to display | | onAddWidget | (type: string) => void | No | Callback when adding a new widget | | onRemoveWidget | (id: string) => void | No | Callback when removing a widget | | onLayoutChange | (layout: GridStackNode[]) => void | No | Callback when layout changes | | gridOptions | Partial<GridStackOptions> | No | Custom GridStack options |

DashboardWidget

interface DashboardWidget {
  id: string;
  type: 'TEXT' | 'NUMBER' | 'CHART' | 'TABLE' | 'IMAGE';
  x: number;        // Grid X position
  y: number;        // Grid Y position
  w: number;        // Width in grid units
  h: number;        // Height in grid units
  content: ReactNode; // React component to render
}

Usage Examples

Basic Dashboard

import { DraggableDashboard } from 'apptimus-dashboard';

const widgets = [
  {
    id: '1',
    type: 'TEXT',
    x: 0,
    y: 0,
    w: 4,
    h: 2,
    content: <div>Hello World</div>
  },
  {
    id: '2',
    type: 'CHART',
    x: 4,
    y: 0,
    w: 8,
    h: 4,
    content: <ChartComponent data={chartData} />
  }
];

<DraggableDashboard widgets={widgets} />

With Layout Persistence

import { useState, useEffect } from 'react';
import { DraggableDashboard } from 'apptimus-dashboard';

function Dashboard() {
  const [widgets, setWidgets] = useState([]);

  // Load saved layout
  useEffect(() => {
    const saved = localStorage.getItem('dashboard-layout');
    if (saved) {
      setWidgets(JSON.parse(saved));
    }
  }, []);

  // Save layout changes
  const handleLayoutChange = (layout) => {
    const updated = widgets.map(widget => {
      const layoutItem = layout.find(item => item.id === widget.id);
      if (layoutItem) {
        return {
          ...widget,
          x: layoutItem.x || 0,
          y: layoutItem.y || 0,
          w: layoutItem.w || 4,
          h: layoutItem.h || 2,
        };
      }
      return widget;
    });
    setWidgets(updated);
    localStorage.setItem('dashboard-layout', JSON.stringify(updated));
  };

  return (
    <DraggableDashboard
      widgets={widgets}
      onLayoutChange={handleLayoutChange}
    />
  );
}

Custom Grid Options

<DraggableDashboard
  widgets={widgets}
  gridOptions={{
    column: 16,        // 16-column grid
    cellHeight: 100,   // Taller cells
    margin: 5,         // Smaller margins
    disableResize: false,
    disableDrag: false,
    animate: true,
  }}
/>

Adding Widgets with Modal

import { useState } from 'react';
import { Modal } from '@apptimus-ui/modal';
import { DraggableDashboard } from 'apptimus-dashboard';

function DashboardWithAdd() {
  const [widgets, setWidgets] = useState([]);
  const [showModal, setShowModal] = useState(false);

  const handleAddWidget = (type) => {
    const newWidget = {
      id: Date.now().toString(),
      type,
      x: 0,
      y: 0,
      w: 4,
      h: 2,
      content: <WidgetComponent type={type} />
    };
    setWidgets([...widgets, newWidget]);
    setShowModal(false);
  };

  return (
    <>
      <button onClick={() => setShowModal(true)}>Add Widget</button>
      <DraggableDashboard
        widgets={widgets}
        onAddWidget={handleAddWidget}
      />
      {showModal && (
        <Modal onClose={() => setShowModal(false)}>
          <WidgetTypeSelector onSelect={handleAddWidget} />
        </Modal>
      )}
    </>
  );
}

Widget Types

The dashboard supports five widget types. You provide the React components:

• TEXT: Text-based widgets
• NUMBER: Numeric displays
• CHART: Chart visualizations
• TABLE: Data tables (use @apptimus-ui/table)
• IMAGE: Image displays

GridStack Options

You can customize the grid behavior using gridOptions. Common options:

• column: Number of columns (default: 12)
• cellHeight: Height of each cell in pixels (default: 70)
• margin: Margin between cells (default: 10)
• disableResize: Disable widget resizing
• disableDrag: Disable widget dragging
• animate: Enable animations

See GridStack documentation for all options.

TypeScript

Full TypeScript support is included:

import type {
  DraggableDashboardProps,
  DashboardWidget,
  WidgetType,
} from 'apptimus-dashboard';

Next.js Integration

The package is optimized for Next.js with:

• SSR compatibility
• 'use client' directive for client components
• ESM and CJS build outputs

License

MIT