@abdasis/datatable

A powerful, configurable, and modern DataTable component for React/Next.js applications with TailwindCSS and shadcn/ui support.

✨ Features

• 🚀 Client & Server-side rendering support
• 🎨 Customizable UI with your own shadcn/ui components
• 🔧 Advanced configuration panel with persistent settings
• 📱 Responsive design with mobile-friendly interface
• 🔍 Global search & column filtering
• 📊 Sorting, pagination & row selection
• 💾 localStorage persistence for table configurations
• 📤 Export functionality support
• 🎯 TypeScript first with full type safety
• ⚡ Performance optimized with memo and callbacks

📦 Installation

npm install @abdasis/datatable
# or
yarn add @abdasis/datatable
# or
pnpm add @abdasis/datatable

Peer Dependencies

Make sure you have these dependencies installed:

npm install react react-dom @tanstack/react-table @tanstack/match-sorter-utils lucide-react tailwindcss class-variance-authority clsx tailwind-merge

🚀 Quick Start

1. Prepare Your UI Components

The package requires you to provide your own UI components (typically from shadcn/ui):

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table";
// ... import other UI components

const uiComponents = {
  Button,
  Input,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
  // ... other components
};

2. Basic Usage

import { DataTable, type ColumnDef } from "@abdasis/datatable";

interface User {
  id: number;
  name: string;
  email: string;
  status: "active" | "inactive";
}

const columns: ColumnDef<User, any>[] = [
  {
    id: "name",
    header: "Name",
    accessorKey: "name",
  },
  {
    id: "email",
    header: "Email",
    accessorKey: "email",
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
  },
];

const data: User[] = [
  { id: 1, name: "John Doe", email: "[email protected]", status: "active" },
  { id: 2, name: "Jane Smith", email: "[email protected]", status: "inactive" },
];

function MyTable() {
  return (
    <DataTable
      columns={columns}
      data={data}
      uiComponents={uiComponents}
      enableConfigPanel
      tableId="users-table"
    />
  );
}

📋 Required UI Components

You need to provide these components from your UI library (e.g., shadcn/ui):

interface UIComponents {
  // Basic components
  Button: React.ComponentType<any>;
  Input: React.ComponentType<any>;

  // Table components
  Table: React.ComponentType<any>;
  TableBody: React.ComponentType<any>;
  TableCell: React.ComponentType<any>;
  TableHead: React.ComponentType<any>;
  TableHeader: React.ComponentType<any>;
  TableRow: React.ComponentType<any>;

  // Form components
  Checkbox: React.ComponentType<any>;
  Select: React.ComponentType<any>;
  SelectContent: React.ComponentType<any>;
  SelectItem: React.ComponentType<any>;
  SelectTrigger: React.ComponentType<any>;
  SelectValue: React.ComponentType<any>;

  // Dropdown components
  DropdownMenu: React.ComponentType<any>;
  DropdownMenuCheckboxItem: React.ComponentType<any>;
  DropdownMenuContent: React.ComponentType<any>;
  DropdownMenuItem: React.ComponentType<any>;
  DropdownMenuLabel: React.ComponentType<any>;
  DropdownMenuSeparator: React.ComponentType<any>;
  DropdownMenuTrigger: React.ComponentType<any>;

  // Other components
  Badge: React.ComponentType<any>;
}

For TableConfigPanel (additional components):

interface TableConfigUIComponents {
  // All UIComponents above, plus:
  Switch: React.ComponentType<any>;
  Label: React.ComponentType<any>;
  Popover: React.ComponentType<any>;
  PopoverContent: React.ComponentType<any>;
  PopoverTrigger: React.ComponentType<any>;
  Collapsible: React.ComponentType<any>;
  CollapsibleContent: React.ComponentType<any>;
  CollapsibleTrigger: React.ComponentType<any>;
  Separator: React.ComponentType<any>;
}

🎛️ Configuration Panel

Enable the advanced configuration panel for your users:

<DataTable
  columns={columns}
  data={data}
  uiComponents={uiComponents}
  enableConfigPanel={true}
  tableId="my-unique-table"
  onConfigChange={(config) => {
    console.log("Configuration changed:", config);
  }}
/>

The configuration panel provides:

• View mode toggle (List/Board)
• Column visibility controls
• Sorting and filtering options
• Persistent settings via localStorage

🖥️ Server-Side Rendering

For server-side data fetching and pagination:

<DataTable
  columns={columns}
  data={data}
  renderMode="server"
  serverConfig={{
    totalRows: 1000,
    pageCount: 50,
    loading: isLoading,
    onSortingChange: (sorting) => {
      // Handle server-side sorting
    },
    onColumnFiltersChange: (filters) => {
      // Handle server-side filtering
    },
    onPaginationChange: (pagination) => {
      // Handle server-side pagination
    },
    onGlobalFilterChange: (globalFilter) => {
      // Handle server-side global search
    },
  }}
  uiComponents={uiComponents}
/>

🎨 Customization Examples

With Row Actions

<DataTable
  columns={columns}
  data={data}
  uiComponents={uiComponents}
  rowActions={[
    {
      label: "Edit",
      onClick: (row) => console.log("Edit", row),
      icon: <Edit className="h-4 w-4" />,
    },
    {
      label: "Delete",
      onClick: (row) => console.log("Delete", row),
      icon: <Trash className="h-4 w-4" />,
      variant: "destructive",
    },
  ]}
/>

With Filterable Columns

<DataTable
  columns={columns}
  data={data}
  uiComponents={uiComponents}
  filterableColumns={[
    { id: "status", title: "Status" },
    { id: "category", title: "Category" },
  ]}
/>

With Row Selection

<DataTable
  columns={columns}
  data={data}
  uiComponents={uiComponents}
  enableRowSelection={true}
  onRowSelectionChange={(selectedRows) => {
    console.log("Selected rows:", selectedRows);
  }}
/>

📝 API Reference

DataTable Props

| Prop | Type | Default | Description | | ------------------------ | ------------------------------------------------------------------------------- | ----------- | ------------------------------------------ | | columns | ColumnDef<TData, TValue>[] | - | Required. Column definitions | | data | TData[] | - | Required. Table data | | uiComponents | UIComponents | - | Required. UI component implementations | | renderMode | "client" \| "server" | "client" | Rendering mode | | serverConfig | DataTableServerConfig | - | Server-side configuration | | enableGlobalFilter | boolean | true | Enable global search | | enableColumnFilters | boolean | true | Enable column filters | | enableSorting | boolean | true | Enable sorting | | enablePagination | boolean | true | Enable pagination | | enableRowSelection | boolean | false | Enable row selection | | enableColumnVisibility | boolean | true | Enable column visibility toggle | | enableConfigPanel | boolean | false | Enable advanced config panel | | initialPageSize | number | 10 | Initial page size | | tableId | string | "default" | Unique identifier for localStorage | | filterableColumns | Array<{id: string, title: string}> | [] | Columns that can be filtered | | rowActions | Array<{label: string, onClick: Function, icon?: ReactNode, variant?: string}> | [] | Row action buttons | | onRowSelectionChange | (selectedRows: TData[]) => void | - | Row selection callback | | onExport | () => void | - | Export button callback | | onConfigChange | (config: TableConfigState) => void | - | Configuration change callback |

🔧 Development

Setup

git clone <repository-url>
cd quickpay-datatable-npm
npm install

Build

npm run build

Development

npm run dev

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you have any questions or issues, please open an issue on our GitHub repository.

Built with ❤️ by the QuickPay Team