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

``bash
npm install apptimus-dashboard
`

$3

This package requires the following peer dependencies:

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

Quick Start

`tsx
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:
}
]);

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

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

Props

$3

| 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 | No | Custom GridStack options |

$3

`typescript
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

$3

`tsx
import { DraggableDashboard } from 'apptimus-dashboard';

const widgets = [
{
id: '1',
type: 'TEXT',
x: 0,
y: 0,
w: 4,
h: 2,
content:

Hello World

},
{
id: '2',
type: 'CHART',
x: 4,
y: 0,
w: 8,
h: 4,
content:
}
];


`

$3

`tsx
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 (
widgets={widgets}
onLayoutChange={handleLayoutChange}
/>
);
}
`

$3

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

$3

`tsx
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:
};
setWidgets([...widgets, newWidget]);
setShowModal(false);
};

return (
<>
setShowModal(true)}>Add Widget
widgets={widgets}
onAddWidget={handleAddWidget}
/>
{showModal && (
setShowModal(false)}>


)}

);
}
`

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:

`typescript
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