@abaktiar/datagrid

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

• 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