@abaktiar/datagrid

A powerful, feature-rich React DataGrid component with TypeScript support, built on TanStack Table.

🚀 Features

🎯 TypeScript Support - Fully typed with comprehensive TypeScript definitions
⚡ High Performance - Built on TanStack Table with virtualization support
🎨 Customizable Styling - Multiple themes (light/dark) and density options
📊 Rich Data Operations - Sorting, filtering, pagination, and global search
🖱️ Context Menus - Powerful right-click context menus for cells and tables
📤 Export Capabilities - Export to CSV, JSON, and Excel formats
🚀 Floating Action Dock - Customizable floating buttons for bulk operations
🎨 Button Customization - Custom icons, variants, and complete button components
� Flexible Configuration - Extensive customization options
📱 Responsive Design - Mobile-friendly with overflow handling
🎛️ Advanced Features - Row selection, column resizing, and more

📦 Installation

npm install @abaktiar/datagrid

yarn add @abaktiar/datagrid

pnpm add @abaktiar/datagrid

🏗️ Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

📚 Basic Usage

import React from 'react';
import { DataGrid, DataGridColumn } from '@abaktiar/datagrid';
import '@abaktiar/datagrid/styles';

interface User {
  id: number;
  name: string;
  email: string;
  age: number;
}

const data: User[] = [
  { id: 1, name: 'John Doe', email: 'john@example.com', age: 30 },
  { id: 2, name: 'Jane Smith', email: 'jane@example.com', age: 25 },
  // ... more data
];

const columns: DataGridColumn<User>[] = [
  {
    accessorKey: 'id',
    header: 'ID',
    size: 80,
  },
  {
    accessorKey: 'name',
    header: 'Name',
    size: 200,
  },
  {
    accessorKey: 'email',
    header: 'Email',
    size: 250,
  },
  {
    accessorKey: 'age',
    header: 'Age',
    size: 100,
  },
];

function App() {
  return (
    <DataGrid
      data={data}
      columns={columns}
      enableSorting
      enableFiltering
      enablePagination
      enableRowSelection
      pageSize={10}
    />
  );
}

export default App;

🎨 Styling

Import the CSS file in your application:

import '@abaktiar/datagrid/styles';

🔧 Advanced Usage

Context Menus

import { 
  DataGrid, 
  createCopyValueAction, 
  createEmailAction,
  createCommonCellActions 
} from '@abaktiar/datagrid';

const columns: DataGridColumn<User>[] = [
  {
    accessorKey: 'email',
    header: 'Email',
    cellConfig: {
      contextMenu: {
        items: [
          createCopyValueAction(),
          createEmailAction(),
          ...createCommonCellActions(),
        ],
      },
    },
  },
];

Excel Export

import { 
  DataGrid, 
  createExportExcelAction,
  createExcelExportBundle 
} from '@abaktiar/datagrid';

const tableContextMenu = {
  items: [
    createExportExcelAction('users.xlsx'),
    ...createExcelExportBundle(),
  ],
};

<DataGrid
  data={data}
  columns={columns}
  tableContextMenu={tableContextMenu}
/>

Floating Action Dock

The Floating Action Dock provides customizable floating buttons for bulk operations on selected rows:

import {
  DataGrid,
  createCommonFloatingActions,
  createExportSelectedToExcelAction,
  createFloatingActionSeparator
} from '@abaktiar/datagrid';

// Basic floating dock with built-in actions
<DataGrid
  data={data}
  columns={columns}
  enableRowSelection={true}
  floatingActionDock={{
    enabled: true,
    position: 'bottom-center',
    showCount: true,
    items: createCommonFloatingActions({
      enableExportExcel: true,
      enableExportCSV: true,
    }),
  }}
/>

// Advanced customization with custom buttons
const CustomExcelButton = ({ onClick, disabled, children }) => (
  <button
    onClick={onClick}
    disabled={disabled}
    style={{
      background: 'linear-gradient(135deg, #2E8B57, #228B22)',
      color: 'white',
      border: 'none',
      borderRadius: '8px',
      padding: '10px 16px',
      fontSize: '13px',
      fontWeight: '600',
      display: 'flex',
      alignItems: 'center',
      gap: '8px',
    }}
  >
    {children}
  </button>
);

<DataGrid
  data={data}
  columns={columns}
  enableRowSelection={true}
  floatingActionDock={{
    enabled: true,
    position: 'bottom-center',
    items: [
      // Customized built-in actions
      ...createCommonFloatingActions({
        excelOptions: {
          label: 'Premium Excel Export',
          icon: '🚀',
          customButton: CustomExcelButton,
        },
        csvOptions: {
          label: 'Export CSV',
          icon: '📊',
          variant: 'primary',
        },
      }),
      
      // Add separator
      createFloatingActionSeparator(),
      
      // Custom business actions
      {
        label: 'Archive Selected',
        icon: '📦',
        variant: 'default',
        onClick: (selectedData) => {
          console.log('Archiving:', selectedData);
        },
      },
    ],
  }}
/>

Floating Dock Configuration

Option	Type	Default	Description
`enabled`	`boolean`	`false`	Enable the floating dock
`position`	`'bottom-left' \| 'bottom-center' \| 'bottom-right' \| 'top-left' \| 'top-center' \| 'top-right'`	`'bottom-center'`	Dock position
`showCount`	`boolean`	`true`	Show selected items count
`items`	`FloatingActionItem[]`	`[]`	Array of action items

Creating Custom Floating Actions

// Built-in export actions with customization
createExportSelectedToExcelAction({
  // File options
  filename: 'my-export.xlsx',
  columnMapping: { id: 'ID', name: 'Full Name' },
  
  // Visual customization
  label: 'Download Excel',
  icon: '💾',
  variant: 'success',
  className: 'my-custom-class',
  customButton: MyCustomButton,
})

// Completely custom action
{
  label: 'Custom Action',
  icon: '⭐',
  variant: 'primary',
  onClick: (selectedData, selectedIndices) => {
    // Your custom logic here
    console.log('Selected:', selectedData);
  },
  customButton: MyCustomButtonComponent, // Optional
}

Custom Cell Formatting

const columns: DataGridColumn<User>[] = [
  {
    accessorKey: 'age',
    header: 'Age',
    cellConfig: {
      format: (value) => `${value} years old`,
      style: (value) => ({
        color: value < 30 ? 'green' : 'blue',
        fontWeight: 'bold',
      }),
    },
  },
];

Controlled State

import React, { useState } from 'react';
import { DataGrid, SortingState, PaginationState } from '@abaktiar/datagrid';

function ControlledDataGrid() {
  const [sorting, setSorting] = useState<SortingState>([]);
  const [pagination, setPagination] = useState<PaginationState>({
    pageIndex: 0,
    pageSize: 10,
  });

  return (
    <DataGrid
      data={data}
      columns={columns}
      sorting={sorting}
      onSortingChange={setSorting}
      pagination={pagination}
      onPaginationChange={setPagination}
      manualPagination
      rowCount={totalRows}
    />
  );
}

📖 API Reference

DataGrid Props

Prop	Type	Default	Description
`data`	`T[]`	required	Array of data objects
`columns`	`DataGridColumn<T>[]`	required	Column definitions
`enableSorting`	`boolean`	`true`	Enable column sorting
`enableFiltering`	`boolean`	`true`	Enable column filtering
`enablePagination`	`boolean`	`true`	Enable pagination
`enableRowSelection`	`boolean`	`false`	Enable row selection
`enableColumnResizing`	`boolean`	`true`	Enable column resizing
`enableGlobalSearch`	`boolean`	`true`	Enable global search
`pageSize`	`number`	`10`	Default page size
`density`	`'compact' \| 'comfortable' \| 'spacious'`	`'comfortable'`	Table density
`theme`	`'light' \| 'dark' \| 'auto'`	`'light'`	Theme
`loading`	`boolean`	`false`	Show loading indicator
`floatingActionDock`	`FloatingActionDockConfig`	`undefined`	Floating action dock configuration

Column Configuration

interface DataGridColumn<T> {
  accessorKey: string;
  header: string;
  size?: number;
  minSize?: number;
  maxSize?: number;
  enableSorting?: boolean;
  enableFiltering?: boolean;
  enableResizing?: boolean;
  
  // Cell configuration
  cellConfig?: {
    format?: (value: any, row: T) => React.ReactNode;
    style?: React.CSSProperties | ((value: any, row: T) => React.CSSProperties);
    className?: string | ((value: any, row: T) => string);
    align?: 'left' | 'center' | 'right';
    tooltip?: boolean | ((value: any, row: T) => string);
    contextMenu?: {
      items: ContextMenuItem<T>[];
    };
  };
  
  // Header configuration
  headerConfig?: {
    align?: 'left' | 'center' | 'right';
    className?: string;
    tooltip?: string;
  };
}

🛠️ Utility Functions

Context Menu Actions

createCopyValueAction() - Copy cell value to clipboard
createCopyRowAction() - Copy entire row data
createEmailAction() - Open email client
createPhoneAction() - Handle phone number actions
createOpenUrlAction() - Open URLs in new tab
createGoogleSearchAction() - Search value on Google

Table Actions

createExportCsvAction() - Export table to CSV
createExportJsonAction() - Export table to JSON
createExportExcelAction() - Export table to Excel
createPrintAction() - Print table
createRefreshAction() - Refresh table data

Floating Action Utilities

createExportSelectedToExcelAction() - Excel export for selected rows
createExportSelectedToCSVAction() - CSV export for selected rows
createFloatingActionSeparator() - Visual separator for floating actions
createCommonFloatingActions() - Bundle of common floating actions

Excel Export Utilities

createExcelExportBundle() - Complete Excel export menu
createQuickExcelExport() - Quick export function
excelExportPresets - Predefined export configurations

🎨 Theming & Customization

The DataGrid supports multiple themes and customization options:

<DataGrid
  data={data}
  columns={columns}
  theme="dark"
  density="compact"
  className="my-custom-grid"
  tableClassName="my-table"
  headerClassName="my-header"
  bodyClassName="my-body"
/>

CSS Custom Properties

You can customize the appearance using CSS custom properties:

:root {
  --datagrid-primary-color: #3b82f6;
  --datagrid-border-color: #e5e7eb;
  --datagrid-header-bg: #f9fafb;
  --datagrid-row-hover-bg: #f3f4f6;
}

🔍 Search Configuration

<DataGrid
  data={data}
  columns={columns}
  searchConfig={{
    enabled: true,
    placeholder: 'Search users...',
    position: 'top',
    showIcon: true,
    debounceMs: 300,
  }}
/>

📱 Responsive Design

The DataGrid automatically handles overflow and provides smooth scrolling on mobile devices:

<DataGrid
  data={data}
  columns={columns}
  density="compact" // Better for mobile
  searchConfig={{ position: 'top' }}
/>

🚀 Performance Tips

Use memo for custom cell renderers
Virtualization is automatically handled for large datasets
Debounced search reduces unnecessary re-renders
Column sizing - Set appropriate default sizes

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

📝 Changelog

1.1.0

🚀 NEW: Floating Action Dock - Customizable floating buttons for bulk operations
🎨 NEW: Button Customization - Custom icons, variants, and complete button components
📊 Enhanced Export - Floating Excel and CSV export for selected rows
⚡ Smooth Animations - Polished enter/exit animations for floating dock
🔧 Flexible Configuration - Extensive customization options for floating actions
📚 Comprehensive Examples - Multiple styling themes (Material, Glass, Neon)

1.0.1

Bug fixes and performance improvements
Enhanced TypeScript definitions

1.0.0

Initial release
Full TypeScript support
TanStack Table integration
Context menu functionality
Excel export capabilities
Responsive design
Multiple themes and densities

Made with ❤️ by abaktiar