Smart Datatable

by AlgoDomain

Powerful, flexible data table: client, server, and hybrid modes. Advanced filtering, sorting, pagination, selection, column management with reset, and localStorage persistence.

Install and Configure

Requirements: React 18+ and Tailwind CSS 4.x+

Install using your package manager:

pnpm add @algodomain/smart-datatable
npm i @algodomain/smart-datatable
yarn add @algodomain/smart-datatable

Ensure Tailwind scans package classes in your project:

/* Tailwind v4 style */
@source "../node_modules/@algodomain/smart-datatable/dist/index.js";
/* OR */
@source "../node_modules/@algodomain/smart-datatable/dist/index.cjs";

Import styles once in your app:

import "@algodomain/smart-datatable/style.css";

Basics

React + TypeScript component styled with Tailwind and shadcn/ui
Core import: import { DataTable } from "@algodomain/smart-datatable"

Defining Columns

interface Task {
  id: string;
  title: string;
  status: string;
  priority: string;
  estimatedHours: number;
  createdAt: Date | string;
  assignee: string;
}

const columns = [
  {
    id: "id",
    header: "Task ID",
    accessorKey: "id",
    width: 100,
    sortable: true,
    filterable: true,
    dataType: "string",
    filterType: "text"
  },
  {
    id: "title",
    header: "Title",
    accessorKey: "title",
    width: 200,
    sortable: true,
    filterable: true,
    dataType: "string",
    textWrap: true
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
    width: 120,
    sortable: true,
    filterable: true,
    dataType: "string",
    filterType: "select",
    filterOptions: [
      { label: "New", value: "New" },
      { label: "In-Progress", value: "In-Progress" },
      { label: "Completed", value: "Completed" }
    ]
  },
  {
    id: "estimatedHours",
    header: "Est. Hours",
    accessorKey: "estimatedHours",
    width: 100,
    sortable: true,
    filterable: true,
    dataType: "number",
    filterType: "number"
  },
  {
    id: "createdAt",
    header: "Created At",
    accessorKey: "createdAt",
    width: 180,
    sortable: true,
    filterable: true,
    dataType: "date",
    filterType: "date"
  }
];

Modes: Client, Server, Auto

Client: in-memory, fetch once or pass data prop
Server: API-driven pagination/filtering/sort
Auto: hybrid caching; switches to client when fully cached

Client Mode

<DataTable 
  columns={columns} 
  data={myTasks} 
  mode="client" 
  tableId="tasks-table" 
/>

Server Mode

<DataTable 
  columns={columns} 
  api={{ endpoint: "/api/tasks" }} 
  mode="server" 
  backendORM="prisma" 
/>

Auto Mode

<DataTable 
  columns={columns} 
  api={{ endpoint: "/api/tasks" }} 
  mode="auto" 
/>

Filtering

Operators: =, !=, contains, startsWith, endsWith, isEmpty, isNotEmpty, >, <, >=, <=, between
Select filter via filterType="select" with filterOptions

Sorting

Toggle asc → desc → none. Multi-sort supported.

Pagination

Built-in controls and summary. Configure page size options and initial size.

Selection

Single or multiple selection with header checkbox. Use onSelectionChange.

Column Management

Visibility, reorder, resize, freeze, text wrapping
One-click full reset clears localStorage and restores defaults

Persistence & localStorage

Persists visibility, order, widths, freeze, wrapping, filters, sorting, pagination
Use unique tableId to avoid conflicts

Fixed Headers and Table Height

Set maxHeight for sticky headers and scrollable body.

Styling

Tailwind tokens with CSS variables; header background and borders configurable.

Custom Theme

The new theme prop provides comprehensive styling control with support for both hex codes and Tailwind classes.

Basic Theme Example

<DataTable
  columns={columns}
  data={myTasks}
  theme={{
    header: {
      backgroundColor: '#add8e6', // Light blue header (hex)
      textColor: 'text-gray-900' // Dark text (Tailwind class)
    },
    rows: {
      backgroundColor: '#FFFFC5', // Light yellow rows (hex)
      hoverBackgroundColor: 'hover:bg-blue-50', // Hover effect (Tailwind)
      selectedBackgroundColor: '#e6f3ff' // Selected rows (hex)
    },
    container: {
      borderRadius: 'rounded-lg', // Tailwind class
      boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.1)' // CSS shadow
    }
  }}
/>

Corporate Theme

<DataTable
  theme={{
    header: {
      backgroundColor: '#1e40af', // Blue header
      textColor: 'text-white', // White text
      borderColor: 'border-blue-600'
    },
    rows: {
      backgroundColor: '#f8fafc', // Light gray rows
      hoverBackgroundColor: 'hover:bg-blue-50', // Subtle blue hover
      selectedBackgroundColor: '#dbeafe', // Light blue selection
      alternateRowBackgroundColor: '#f1f5f9' // Striped rows
    },
    container: {
      borderStyle: 'border-solid',
      borderColor: 'border-gray-200',
      borderRadius: 'rounded-lg',
      boxShadow: '0 1px 3px 0 rgba(0, 0, 0, 0.1)'
    }
  }}
/>

Modern Dark Theme

<DataTable
  theme={{
    header: {
      backgroundColor: '#374151', // Dark gray header
      textColor: 'text-white',
      borderColor: 'border-gray-600'
    },
    rows: {
      backgroundColor: '#1f2937', // Dark rows
      hoverBackgroundColor: 'hover:bg-gray-700',
      selectedBackgroundColor: '#4b5563',
      textColor: 'text-gray-100'
    },
    container: {
      backgroundColor: '#111827',
      borderStyle: 'border-solid',
      borderColor: 'border-gray-600',
      borderRadius: 'rounded-xl',
      boxShadow: '0 10px 15px -3px rgba(0, 0, 0, 0.3)'
    }
  }}
/>

Border Style Examples

// No Border (Clean Look)
theme={{
  container: {
    borderStyle: 'border-none',
    boxShadow: '0 4px 6px -1px rgba(0, 0, 0, 0.1)'
  }
}}

// Dashed Border
theme={{
  container: {
    borderStyle: 'border-dashed',
    borderColor: 'border-blue-300'
  }
}}

// Custom CSS Border
theme={{
  container: {
    borderStyle: '3px solid',
    borderColor: '#ff0000'
  }
}}

Theme Configuration Options

interface DataTableTheme {
  header?: {
    backgroundColor?: string; // hex like '#f8f9fa' or Tailwind like 'bg-blue-100'
    textColor?: string; // hex or Tailwind like 'text-gray-900'
    borderColor?: string; // hex or Tailwind like 'border-gray-200'
    borderStyle?: string; // CSS border style like '1px solid'
  };
  rows?: {
    backgroundColor?: string; // default row background
    hoverBackgroundColor?: string; // hover state
    selectedBackgroundColor?: string; // selected row background
    alternateRowBackgroundColor?: string; // for striped tables
    textColor?: string;
    borderColor?: string;
    borderStyle?: string;
  };
  container?: {
    backgroundColor?: string;
    borderColor?: string; // hex like '#ff0000' or Tailwind like 'border-red-500'
    borderStyle?: string; // Tailwind like 'border-dashed', 'border-dotted', 'border-none' or CSS like '1px solid'
    borderRadius?: string; // hex or Tailwind like 'rounded-lg'
    padding?: string; // CSS padding
    boxShadow?: string; // CSS shadow
  };
  columns?: {
    borderColor?: string;
    borderStyle?: string;
    separatorColor?: string; // for column separators
  };
  controls?: {
    backgroundColor?: string;
    textColor?: string;
    buttonBackgroundColor?: string;
    buttonHoverBackgroundColor?: string;
    borderColor?: string;
  };
}

Backward Compatibility

The new theme system is fully backward compatible:

Existing headerBackgroundColor prop continues to work
All default styles remain unchanged
Theme values override legacy props when both are provided

Backend Integration with ORM Adapters

custom, prisma, mongoose, typeorm adapters shape server POST payloads

Error Handling

Non-OK server responses show in-table errors; provide onError for global handling.

Performance Tips

Prefer server/auto for very large datasets
Use select filters for categorical data

Complete Properties Reference

See README for the full reference of DataTable and ColumnDef properties, dependencies, and conflicts.

Quick Reference Examples

Minimal client table with data
Client with API endpoint
Server and Auto minimal setups