@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

or

yarn add @abaktiar/datagrid

or

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: '[email protected]', age: 30 },
  { id: 2, name: 'Jane Smith', email: '[email protected]', 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

1. Use memo for custom cell renderers
2. Virtualization is automatically handled for large datasets
3. Debounced search reduces unnecessary re-renders
4. 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

• GitHub Repository
• npm Package
• Issues

📝 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