@ttoss/react-dashboard

About

A comprehensive React dashboard module that provides customizable dashboard functionality with filters, templates, responsive grid layouts, and an edit mode to build and save layouts. This module enables you to create data-rich dashboards with support for multiple card types, filter systems, and template management.

Installation

pnpm add @ttoss/react-dashboard

Getting Started

Provider Setup

If you're using the Dashboard component directly, you don't need to set up the provider separately as it wraps the DashboardProvider internally. However, if you need to use the useDashboard hook in other components, you can wrap your application with the DashboardProvider:

import { DashboardProvider } from '@ttoss/react-dashboard';
import { ThemeProvider } from '@ttoss/ui';
import type {
  DashboardTemplate,
  DashboardFilter,
} from '@ttoss/react-dashboard';

const templates: DashboardTemplate[] = [];
const filters: DashboardFilter[] = [];
const selectedTemplate: DashboardTemplate | undefined = undefined;

ReactDOM.render(
  <React.StrictMode>
    <ThemeProvider>
      <DashboardProvider
        filters={filters}
        templates={templates}
        selectedTemplate={selectedTemplate}
      >
        <App />
      </DashboardProvider>
    </ThemeProvider>
  </React.StrictMode>,
  document.getElementById('root')
);

Basic Dashboard Usage

import { Dashboard } from '@ttoss/react-dashboard';
import type {
  DashboardTemplate,
  DashboardFilter,
} from '@ttoss/react-dashboard';
import { DashboardFilterType } from '@ttoss/react-dashboard';

const MyDashboard = () => {
  const selectedTemplate: DashboardTemplate = {
    id: 'default',
    name: 'Default Template',
    description: 'My default dashboard layout',
    grid: [
      {
        i: 'card-1',
        x: 0,
        y: 0,
        w: 4,
        h: 4,
        card: {
          title: 'Total Revenue',
          numberType: 'currency',
          type: 'bigNumber',
          sourceType: [{ source: 'api' }],
          data: {
            api: { total: 150000 },
          },
        },
      },
    ],
  };

  const filters: DashboardFilter[] = [
    {
      key: 'date-range',
      type: DashboardFilterType.DATE_RANGE,
      label: 'Date Range',
      value: { from: new Date(), to: new Date() },
    },
  ];

  return (
    <Dashboard
      selectedTemplate={selectedTemplate}
      templates={[]}
      filters={filters}
      loading={false}
    />
  );
};

Editable Dashboard Usage

Use editable mode to let users reorganize cards, remove/add cards from a catalog, save changes to the current template, or save a cloned template.

import { Dashboard, DEFAULT_CARD_CATALOG } from '@ttoss/react-dashboard';
import type {
  DashboardTemplate,
  CardCatalogItem,
} from '@ttoss/react-dashboard';

const cardCatalog: CardCatalogItem[] = DEFAULT_CARD_CATALOG;

const selectedTemplate: DashboardTemplate = {
  id: 'default',
  name: 'Performance Dashboard',
  editable: true,
  grid: [],
};

<Dashboard
  selectedTemplate={selectedTemplate}
  templates={[selectedTemplate]}
  filters={[]}
  editable
  cardCatalog={cardCatalog}
  onSaveLayout={(template) => {
    // Persist edited layout for current template
  }}
  onSaveAsNewTemplate={(template) => {
    // Persist cloned template
  }}
  onCancelEdit={() => {
    // Optional callback when user cancels edit mode
  }}
/>;

Components

Dashboard

The main dashboard component that orchestrates the entire dashboard experience.

import { Dashboard } from '@ttoss/react-dashboard';

<Dashboard
  selectedTemplate={selectedTemplate}
  templates={templates}
  filters={filters}
  loading={false}
  headerChildren={<CustomHeaderContent />}
  onFiltersChange={(filters) => {
    // Handle filter changes
  }}
/>;

Props:

| Prop | Type | Default | Description | | --------------------- | --------------------------------------- | --------------- | ------------------------------------------------------ | | selectedTemplate | DashboardTemplate \| undefined | - | The template to display in the dashboard | | templates | DashboardTemplate[] | [] | Array of dashboard templates | | filters | DashboardFilter[] | [] | Array of dashboard filters | | loading | boolean | false | Loading state for the dashboard | | cardCatalog | CardCatalogItem[] | default catalog | Card types available in "Add item" while editing | | headerChildren | React.ReactNode | - | Additional content to render in the header | | onFiltersChange | (filters: DashboardFilter[]) => void | - | Callback when filters change | | editable | boolean | false | Enables dashboard edit mode controls | | onSaveLayout | (template: DashboardTemplate) => void | - | Called when user saves edits to current template | | onSaveAsNewTemplate | (template: DashboardTemplate) => void | - | Called when user saves edited layout as a new template | | onCancelEdit | () => void | - | Called when user cancels edit mode |

DashboardProvider

Context provider that manages dashboard state (filters and templates).

import { DashboardProvider } from '@ttoss/react-dashboard';

<DashboardProvider
  filters={filters}
  templates={templates}
  selectedTemplate={selectedTemplate}
  onFiltersChange={handleFiltersChange}
>
  {children}
</DashboardProvider>;

Props:

| Prop | Type | Default | Description | | --------------------- | --------------------------------------- | --------------- | --------------------------------- | | children | React.ReactNode | - | Child components | | filters | DashboardFilter[] | [] | Filter state | | templates | DashboardTemplate[] | [] | Template state | | cardCatalog | CardCatalogItem[] | default catalog | Card types available in edit mode | | selectedTemplate | DashboardTemplate \| undefined | - | The template to display | | onFiltersChange | (filters: DashboardFilter[]) => void | - | Callback when filters change | | editable | boolean | false | Enables dashboard edit controls | | onSaveLayout | (template: DashboardTemplate) => void | - | Saves edits in current template | | onSaveAsNewTemplate | (template: DashboardTemplate) => void | - | Saves edits as a new template | | onCancelEdit | () => void | - | Called when editing is canceled |

useDashboard Hook

Hook to access and modify dashboard state.

import { useDashboard } from '@ttoss/react-dashboard';

const MyComponent = () => {
  const {
    filters,
    updateFilter,
    templates,
    selectedTemplate,
    editable,
    isEditMode,
    startEdit,
    cancelEdit,
    saveEdit,
    addCard,
  } = useDashboard();

  // Use dashboard state
  const handleFilterChange = (key: string, value: DashboardFilterValue) => {
    updateFilter(key, value);
  };

  if (editable && !isEditMode) {
    startEdit();
  }
};

Returns:

| Property | Type | Description | | -------------------- | ---------------------------------------------------------- | --------------------------------------------------- | | filters | DashboardFilter[] | Current filter state | | updateFilter | (key: string, value: DashboardFilterValue) => void | Updates a specific filter by key | | templates | DashboardTemplate[] | Current template state | | selectedTemplate | DashboardTemplate \| undefined | Currently selected template | | cardCatalog | CardCatalogItem[] | Card catalog used by add-card drawer | | editable | boolean | Whether edit controls are enabled | | isEditMode | boolean | Whether dashboard is currently in edit mode | | editingGrid | DashboardGridItem[] \| null | Temporary grid while editing | | startEdit | () => void | Starts edit mode | | cancelEdit | () => void | Cancels edit mode and discards temporary changes | | saveEdit | () => void | Saves editing grid into current template callback | | saveAsNew | () => void | Opens save-as-new flow | | saveAsNewModalOpen | boolean | Save-as-new drawer state | | confirmSaveAsNew | (title: string) => void | Confirms save-as-new action | | cancelSaveAsNew | () => void | Cancels save-as-new flow | | addCard | (item: CardCatalogItem) => void | Adds a card to editing grid | | removeCard | (id: string) => void | Removes card from editing grid | | updateCard | (id: string, cardPatch: Record<string, unknown>) => void | Patches a card in editing grid | | onLayoutChange | (layout: Layout[]) => void | Syncs edited card positions/sizes from grid changes |

DashboardCard

Component for rendering individual dashboard cards. Currently supports bigNumber type.

import { DashboardCard } from '@ttoss/react-dashboard';

<DashboardCard
  title="Total Revenue"
  description="Revenue from all sources"
  numberType="currency"
  numberDecimalPlaces={2}
  type="bigNumber"
  sourceType={[{ source: 'api' }]}
  data={{
    api: { total: 150000 },
  }}
  trend={{
    value: 15.5,
    status: 'positive',
  }}
/>;

Props:

| Prop | Type | Default | Description | | --------------------- | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | id | string | - | Card identification | | title | string | - | Card title | | description | string | - | Optional card description | | icon | string | - | Optional icon name | | color | string | - | Optional color for the card | | variant | CardVariant | - | Card variant ('default' \| 'dark' \| 'light-green') | | numberType | CardNumberType | - | Number formatting type ('number' \| 'percentage' \| 'currency') | | numberDecimalPlaces | number | 2 | Optional number of decimal places for number formatting (defaults to 2) | | type | DashboardCardType | - | Card type ('bigNumber' \| 'pieChart' \| 'barChart' \| 'lineChart' \| 'table' \| 'list') | | sourceType | CardSourceType[] | - | Data source configuration | | labels | Array<string \| number> | - | Optional labels for the card | | data | DashboardCardData | - | Card data from various sources | | trend | TrendIndicator | - | Optional trend indicator | | additionalInfo | string | - | Optional additional information text | | status | StatusIndicator | - | Optional status indicator | | suffix | string | - | Optional text appended after the formatted number (e.g. "kg", "un", "p.p."). Not shown when value is undefined. |

DashboardFilters

Component that automatically renders filters based on the dashboard state.

import { DashboardFilters } from '@ttoss/react-dashboard';

// Automatically renders filters from DashboardProvider context
<DashboardFilters />;

This component reads filters from the DashboardProvider context and renders the appropriate filter component for each filter type.

DashboardHeader

Header component that displays filters and optional custom content.

import { DashboardHeader } from '@ttoss/react-dashboard';

<DashboardHeader>
  <CustomActionButtons />
</DashboardHeader>;

Props:

| Prop | Type | Description | | ---------- | ----------------- | ------------------------------------ | | children | React.ReactNode | Optional content to render in header |

DashboardGrid

Responsive grid layout component that displays dashboard cards using react-grid-layout.

import { DashboardGrid } from '@ttoss/react-dashboard';

<DashboardGrid loading={false} />;

Props:

| Prop | Type | Default | Description | | --------- | --------- | ------- | ----------------------------- | | loading | boolean | - | Shows loading spinner if true |

DashboardSectionDivider

Component that displays a section divider with a title and horizontal line to visually separate sections in the dashboard grid.

import { DashboardSectionDivider } from '@ttoss/react-dashboard';

<DashboardSectionDivider title="Performance Metrics" />;

Props:

| Prop | Type | Default | Description | | ------- | -------- | ------- | -------------------------- | | title | string | - | The title of the section | | type | string | - | Must be 'sectionDivider' |

Usage in Dashboard Grid:

Section dividers can be added to the dashboard grid just like regular cards. They help organize dashboard content into logical sections:

const selectedTemplate: DashboardTemplate = {
  id: 'default',
  name: 'Default Template',
  grid: [
    {
      i: 'card-1',
      x: 0,
      y: 0,
      w: 4,
      h: 4,
      card: {
        id: 'abc-123',
        title: 'Total Revenue',
        type: 'bigNumber',
        // ... other card properties
      },
    },
    {
      i: 'divider-1',
      x: 0,
      y: 4,
      w: 12, // Full width for divider
      h: 2, // Smaller height for divider
      card: {
        type: 'sectionDivider',
        title: 'Performance Metrics',
      },
    },
    {
      i: 'card-2',
      x: 0,
      y: 6,
      w: 4,
      h: 4,
      card: {
        id: 'def-456',
        title: 'ROAS',
        type: 'bigNumber',
        // ... other card properties
      },
    },
  ],
};

Filter Types

Text Filter

A text input filter for string values.

import { DashboardFilterType } from '@ttoss/react-dashboard';

const textFilter: DashboardFilter = {
  key: 'search',
  type: DashboardFilterType.TEXT,
  label: 'Search',
  placeholder: 'Enter search term...',
  value: '',
  onChange: (value) => {
    console.log('Search:', value);
  },
};

Select Filter

A dropdown select filter for predefined options.

const selectFilter: DashboardFilter = {
  key: 'status',
  type: DashboardFilterType.SELECT,
  label: 'Status',
  value: 'active',
  options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' },
  ],
  onChange: (value) => {
    console.log('Status:', value);
  },
};

Date Range Filter

A date range picker with optional presets.

const dateRangeFilter: DashboardFilter = {
  key: 'date-range',
  type: DashboardFilterType.DATE_RANGE,
  label: 'Date Range',
  value: { from: new Date(), to: new Date() },
  presets: [
    {
      label: 'Last 7 days',
      getValue: () => ({
        from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
        to: new Date(),
      }),
    },
    {
      label: 'Last 30 days',
      getValue: () => ({
        from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
        to: new Date(),
      }),
    },
  ],
  onChange: (value) => {
    console.log('Date range:', value);
  },
};

Types

DashboardTemplate

interface DashboardTemplate {
  id: string;
  name: string;
  description?: string;
  grid: DashboardGridItem[];
  editable?: boolean;
}

DashboardGridItem

interface DashboardGridItem extends ReactGridLayout.Layout {
  card: DashboardCard | SectionDivider;
}

DashboardFilter

interface DashboardFilter {
  key: string;
  type: DashboardFilterType;
  label: string;
  placeholder?: string;
  value: DashboardFilterValue;
  onChange?: (value: DashboardFilterValue) => void;
  options?: { label: string; value: string | number | boolean }[];
  presets?: { label: string; getValue: () => DateRange }[];
}

DashboardFilterValue

type DashboardFilterValue =
  | string
  | number
  | boolean
  | { from: Date; to: Date };

DashboardFilterType

enum DashboardFilterType {
  TEXT = 'text',
  SELECT = 'select',
  DATE_RANGE = 'date-range',
  NUMBER = 'number',
  BOOLEAN = 'boolean',
}

DashboardCard

See DashboardCard section for full interface.

CardCatalogItem

Serializable card catalog item used by edit mode to add new cards to the layout.

type CardCatalogItem = Pick<DashboardGridItem, 'w' | 'h' | 'card'>;

CardNumberType

type CardNumberType = 'number' | 'percentage' | 'currency';

CardSourceType

type CardSourceType = {
  source: 'meta' | 'oneclickads' | 'api';
  level?: 'adAccount' | 'campaign' | 'adSet' | 'ad';
};

DashboardCardType

type DashboardCardType =
  | 'bigNumber'
  | 'pieChart'
  | 'barChart'
  | 'lineChart'
  | 'table'
  | 'list';

CardVariant

type CardVariant = 'default' | 'dark' | 'light-green';

TrendIndicator

Trend indicator that displays a percentage change with visual indicators.

type TrendIndicator = {
  value: number;
  status?: 'positive' | 'negative' | 'neutral';
  type?: 'higher' | 'lower';
};

Behavior:

• Positive status: Displays an up arrow icon and the percentage value (e.g., "10.5% vs. anterior")
• Negative status: Displays a down arrow icon and the percentage value (e.g., "5.2% vs. anterior")
• Neutral status: Displays no arrow icon, only the percentage value (e.g., "0.0% vs. anterior")
• The value is always formatted to 1 decimal place followed by "%"
• Note: Positive values do not include a "+" sign prefix

Example:

trend={{
  value: 15.5,
  status: 'positive',
  type: 'higher', // Optional: indicates if higher/lower is good
}}

StatusIndicator

Status indicator that displays text with an optional icon.

type StatusIndicator = {
  text: string;
  icon?: string;
};

Example:

status={{
  text: 'Active',
  icon: 'mdi:check-circle',
}}

SectionDivider

Type for section divider items in the dashboard grid.

type SectionDivider = {
  type: 'sectionDivider';
  title: string;
};

Example:

{
  i: 'divider-1',
  x: 0,
  y: 4,
  w: 12,
  h: 2,
  card: {
    type: 'sectionDivider',
    title: 'Performance Metrics',
  },
}

Complete Example

import { Dashboard } from '@ttoss/react-dashboard';
import type {
  DashboardTemplate,
  DashboardFilter,
} from '@ttoss/react-dashboard';
import { DashboardFilterType } from '@ttoss/react-dashboard';

const App = () => {
  const selectedTemplate: DashboardTemplate = {
    id: 'default',
    name: 'Default Dashboard',
    grid: [
      {
        i: 'revenue',
        x: 0,
        y: 0,
        w: 4,
        h: 4,
        card: {
          id: 'abc-123',
          title: 'Total Revenue',
          numberType: 'currency',
          type: 'bigNumber',
          sourceType: [{ source: 'api' }],
          data: {
            api: { total: 150000 },
          },
          trend: {
            value: 15.5,
            status: 'positive',
          },
        },
      },
      {
        i: 'roas',
        x: 4,
        y: 0,
        w: 4,
        h: 4,
        card: {
          id: 'abc-456',
          title: 'ROAS',
          numberType: 'number',
          numberDecimalPlaces: 2,
          type: 'bigNumber',
          sourceType: [{ source: 'api' }],
          data: {
            api: { total: 3.5 },
          },
          variant: 'light-green',
        },
      },
    ],
  };

  // Optional: Keep templates array if you need to switch between templates
  const templates: DashboardTemplate[] = [selectedTemplate];

  const filters: DashboardFilter[] = [
    {
      key: 'date-range',
      type: DashboardFilterType.DATE_RANGE,
      label: 'Date Range',
      value: {
        from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
        to: new Date(),
      },
      presets: [
        {
          label: 'Last 7 days',
          getValue: () => ({
            from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
            to: new Date(),
          }),
        },
        {
          label: 'Last 30 days',
          getValue: () => ({
            from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
            to: new Date(),
          }),
        },
      ],
    },
  ];

  const handleFiltersChange = (updatedFilters: DashboardFilter[]) => {
    console.log('Filters changed:', updatedFilters);
    // Update your data fetching logic here
  };

  return (
    <Dashboard
      selectedTemplate={selectedTemplate}
      templates={templates}
      filters={filters}
      loading={false}
      onFiltersChange={handleFiltersChange}
    />
  );
};

License

MIT