DataTable

A feature-rich, server-side data table implementation built with React, TanStack Table, Laravel, and Inertia.js. This data table provides pagination, sorting, search, bulk actions, and column visibility controls out of the box.

📸 Demo

Main datatable view with pagination, search, sorting, column visibility, bulk actions

📱 More Screenshots

Create user page (Part of CRUD)

Edit user page (Part of CRUD)

🛠️ Tech Stack

Frontend Stack

React 18 - Modern UI library with hooks and concurrent features
TypeScript - Type-safe JavaScript with excellent developer experience
Inertia.js - Modern monolith approach connecting Laravel and React seamlessly
TanStack Table - Powerful headless table library for complex data interactions
Tailwind CSS - Utility-first CSS framework for rapid UI development
Radix UI - Unstyled, accessible UI primitives for custom design systems
Lucide Icons - Beautiful & consistent icon library
Vite - Fast build tool and development server

Backend Stack

Laravel 11 - Elegant PHP framework with rich ecosystem
PHP 8.3+ - Modern PHP with performance improvements and type safety
MySQL/PostgreSQL - Robust database with full-text search capabilities
Laravel Resources - API resource transformation for consistent data formatting
Laravel Pagination - Built-in pagination with query string persistence

🚀 Getting Started

Prerequisites

Make sure you have the following installed on your system:

PHP 8.2+ with extensions: mbstring, xml, ctype, json, bcmath, fileinfo, tokenizer
Composer - PHP dependency manager
Node.js 18+ and npm (or yarn/pnpm)
MySQL 8.0+ or PostgreSQL 13+
Git

Installation

Clone the repository

git clone https://github.com/your-username/data-table.git
cd data-table

Install PHP dependencies
```
composer install
```

Install Node.js dependencies

npm install
# or
yarn install
# or
pnpm install

Environment setup

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

Configure your .env file

APP_NAME="Data Table"
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=data_table
DB_USERNAME=your_username
DB_PASSWORD=your_password

Database setup

# Create database (make sure MySQL/PostgreSQL is running)
# Then run migrations
php artisan migrate

# Seed with sample data (optional)
php artisan db:seed

Build frontend assets

# For development
npm run dev

# For production
npm run build

Start the development server

# In one terminal - Laravel server
php artisan serve

# In another terminal - Vite dev server (for hot reload)
npm run dev

Access the application

Open your browser and visit: http://localhost:8000

Quick Development Commands

# Watch for file changes (auto-reload)
npm run dev

# Run Laravel with specific host/port
php artisan serve --host=0.0.0.0 --port=8080

# Clear application cache
php artisan cache:clear
php artisan config:clear
php artisan view:clear

# Run database migrations
php artisan migrate:fresh --seed

# Generate TypeScript types for Laravel routes (if using Ziggy)
php artisan ziggy:generate

Docker Setup (Alternative)

If you prefer using Docker:

# Using Laravel Sail
./vendor/bin/sail up -d

# Install dependencies inside container
./vendor/bin/sail composer install
./vendor/bin/sail npm install

# Run migrations
./vendor/bin/sail artisan migrate --seed

# Build assets
./vendor/bin/sail npm run dev

Troubleshooting

Common Issues:

Vite connection refused: Make sure both php artisan serve and npm run dev are running
Database connection error: Verify database credentials in .env
Permission errors: Set proper permissions:
```
chmod -R 775 storage bootstrap/cache
```
Missing APP_KEY: Run php artisan key:generate

✨ Features

🔍 Server-side Search - Debounced search with query parameter persistence
📄 Server-side Pagination - Configurable page sizes with navigation controls
🔄 Server-side Sorting - Click-to-sort columns with visual indicators
✅ Bulk Actions - Select multiple rows and perform batch operations
🗑️ Bulk Delete - Built-in bulk delete functionality with confirmation dialog
👁️ Column Visibility - Show/hide columns with localStorage persistence
📱 Responsive Design - Works on desktop and mobile devices
🎯 TypeScript Support - Fully typed with generic interfaces
🎨 Customizable - Extensible styling and behavior

🧩 Components Overview

Core Components

Component	File	Description
`DataTable`	`resources/js/components/datatable.tsx`	Main table component with all features
`DataTableToolbar`	`resources/js/components/datatable-toolbar.tsx`	Search, bulk actions, column visibility
`DataTablePagination`	`resources/js/components/datatable-pagination.tsx`	Pagination controls and page size selector
`DataTableColumnHeader`	`resources/js/components/datatable-column-header.tsx`	Sortable column headers with sort indicators

Supporting Files

File	Description
`resources/js/hooks/use-column-visibility.tsx`	Hook for managing column visibility with localStorage
`resources/js/types/index.d.ts`	TypeScript interfaces and types

🚀 Quick Start

1. Basic Implementation

import { DataTable } from '@/components/datatable';
import { ColumnDef } from '@tanstack/react-table';

// Define your data type
interface User {
    id: number;
    name: string;
    email: string;
    created_at: string;
}

// Define columns
const columns: (ColumnDef<User> & { enable_sorting?: boolean })[] = [
    {
        accessorKey: 'id',
        header: 'ID',
        enable_sorting: true,
    },
    {
        accessorKey: 'name',
        header: 'Name',
        enable_sorting: true,
    },
    {
        accessorKey: 'email',
        header: 'Email',
        enable_sorting: true,
    },
];

// Use in your page component
function UsersPage({ usersData }: { usersData: PaginatedData<User> }) {
    return <DataTable columns={columns} data={usersData.data} paginatedData={usersData} tableKey="users-table" />;
}

2. With Bulk Actions

<DataTable
    columns={columns}
    data={usersData.data}
    paginatedData={usersData}
    activeBulkActions={true}
    bulkDelete={{
        route: route('users.bulk-delete'),
        title: 'Delete Users',
        description: 'Are you sure you want to delete the selected users?',
    }}
    tableKey="users-table"
/>

💻 Frontend Usage

Column Definition

Columns follow TanStack Table's ColumnDef interface with an additional enable_sorting property:

const columns: (ColumnDef<YourDataType> & { enable_sorting?: boolean })[] = [
    {
        accessorKey: 'field_name',
        header: 'Display Name',
        enable_sorting: true, // Enable server-side sorting for this column
        cell: ({ row }) => {
            // Custom cell rendering
            return <div>{row.original.field_name}</div>;
        },
    },
    {
        header: 'Actions',
        accessorKey: 'actions',
        enable_sorting: false,
        cell: ({ row }) => {
            return (
                <div className="flex gap-2">
                    <Button onClick={() => editItem(row.original.id)}>Edit</Button>
                    <Button onClick={() => deleteItem(row.original.id)}>Delete</Button>
                </div>
            );
        },
    },
];

Custom Bulk Actions

const bulkActions: BulkAction<User>[] = [
    {
        label: 'Export Selected',
        icon: Download,
        onClick: (selectedRows) => {
            // Handle export
            exportUsers(selectedRows);
        },
    },
    {
        label: 'Archive Selected',
        icon: Archive,
        className: 'text-orange-600',
        onClick: (selectedRows) => {
            // Handle archive
            archiveUsers(selectedRows);
        },
    },
];

<DataTable
    // ... other props
    bulkActions={bulkActions}
    activeBulkActions={true}
/>;

DataTable Props

interface DataTableProps<TData, TValue> {
    columns: (ColumnDef<TData, TValue> & { enable_sorting?: boolean })[];
    data: TData[];
    paginatedData?: PaginatedData<TData>;
    bulkActions?: BulkAction<TData>[];
    bulkDelete?: {
        route: string;
        title?: string;
        description?: string;
    };
    activeBulkActions?: boolean;
    tableKey?: string; // For localStorage column visibility
}

🛠️ Backend Implementation

1. Controller Method

<?php

namespace App\Http\Controllers;

use App\Http\Resources\UserResource;
use App\Models\User;
use Illuminate\Http\Request;
use Inertia\Inertia;

class UserController extends Controller
{
    public function index(Request $request)
    {
        // Extract query parameters with defaults
        $queryParams = request()->only(['search', 'page', 'per_page', 'sort_by', 'sort_dir']) + [
            'sort_by' => 'id',
            'sort_dir' => 'desc',
            'per_page' => 10,
            'page' => 1
        ];

        $users = User::query()
            // Search functionality
            ->when($request->search, function ($query, $search) {
                $query->where('name', 'like', '%' . $search . '%')
                      ->orWhere('email', 'like', '%' . $search . '%');
            })
            // Sorting
            ->orderBy($queryParams['sort_by'], $queryParams['sort_dir'])
            // Pagination
            ->paginate($queryParams['per_page'])
            ->withQueryString();

        return Inertia::render('users/index', [
            'usersData' => UserResource::collection($users)->additional([
                'queryParams' => $queryParams,
            ]),
        ]);
    }

    // Bulk delete method
    public function bulkDelete(Request $request)
    {
        $request->validate([
            'ids' => 'required|array',
            'ids.*' => 'exists:users,id',
        ]);

        User::whereIn('id', $request->ids)->delete();

        return redirect()->route('users.index')
                        ->with('success', 'Users deleted successfully');
    }
}

2. Resource Collection

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'role' => $this->role,
            'created_at' => $this->created_at->format('M d, Y'),
            'updated_at' => $this->updated_at->format('M d, Y'),
            // Add any other fields you need
        ];
    }
}

3. Routes

// routes/web.php
Route::delete('users/bulk-delete', [UserController::class, 'bulkDelete'])->name('users.bulk-delete');
Route::resource('users', UserController::class);

📚 API Reference

TypeScript Interfaces

// Main data structure returned from backend
interface PaginatedData<T> {
    data: T[];
    queryParams: QueryParams;
    meta: PaginationMeta;
    links: SimplePaginationLinks;
}

// Query parameters for server requests
interface QueryParams {
    search?: string;
    page?: number;
    per_page?: number;
    sort_by?: string | null;
    sort_dir?: 'asc' | 'desc' | null;
    [key: string]: unknown;
}

// Bulk action definition
interface BulkAction<TData> {
    label: string;
    icon?: LucideIcon | IconType | null;
    onClick: (selectedRows: TData[]) => void;
    className?: string; // For custom styling
}

// Pagination metadata from Laravel
interface PaginationMeta {
    current_page: number;
    from: number;
    last_page: number;
    per_page: number;
    to: number;
    total: number;
    links: Array<{
        url: string | null;
        label: string;
        active: boolean;
    }>;
}

🎯 Examples

Complete Users Table Example

// resources/js/pages/users/index.tsx
import { DataTable } from '@/components/datatable';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import {
    AlertDialog,
    AlertDialogAction,
    AlertDialogCancel,
    AlertDialogContent,
    AlertDialogDescription,
    AlertDialogFooter,
    AlertDialogHeader,
    AlertDialogTitle,
    AlertDialogTrigger,
} from '@/components/ui/alert-dialog';
import { ColumnDef } from '@tanstack/react-table';
import { Eye, Pencil, Trash } from 'lucide-react';

const ROLE_COLORS = {
    admin: 'border-blue-500 text-blue-500',
    manager: 'border-green-500 text-green-500',
    user: 'border-gray-500 text-gray-500',
};

const UsersIndex = ({ usersData }: { usersData: PaginatedData<User> }) => {
    const handleDeleteUser = (userId: number) => {
        router.delete(route('users.destroy', userId));
    };

    const columns: (ColumnDef<User> & { enable_sorting?: boolean })[] = [
        {
            accessorKey: 'id',
            header: '#ID',
            enable_sorting: true,
            cell: ({ row }) => <div>#{row.original.id}</div>,
        },
        {
            header: 'Avatar',
            accessorKey: 'avatar',
            enable_sorting: false,
            cell: ({ row }) => (
                <Avatar className="size-10">
                    <AvatarImage src={row.original.avatar} />
                    <AvatarFallback>{row.original.name.charAt(0)}</AvatarFallback>
                </Avatar>
            ),
        },
        {
            accessorKey: 'name',
            header: 'Name',
            enable_sorting: true,
            cell: ({ row }) => (
                <div>
                    <h2 className="text-base font-semibold">{row.original.name}</h2>
                    <p className="text-sm text-gray-500">{row.original.email}</p>
                </div>
            ),
        },
        {
            accessorKey: 'role',
            header: 'Role',
            enable_sorting: true,
            cell: ({ row }) => (
                <Badge variant="outline" className={`capitalize ${ROLE_COLORS[row.original.role as keyof typeof ROLE_COLORS]}`}>
                    {row.original.role}
                </Badge>
            ),
        },
        {
            accessorKey: 'created_at',
            header: 'Created At',
            enable_sorting: true,
        },
        {
            header: 'Actions',
            accessorKey: 'actions',
            enable_sorting: false,
            cell: ({ row }) => (
                <div className="flex flex-row gap-0.5">
                    <Button variant="ghost" size="icon" className="size-8 text-blue-500" asChild>
                        <Link href={route('users.show', row.original.id)}>
                            <Eye className="size-4" />
                        </Link>
                    </Button>
                    <Button variant="ghost" size="icon" className="size-8 text-green-500" asChild>
                        <Link href={route('users.edit', row.original.id)}>
                            <Pencil className="size-4" />
                        </Link>
                    </Button>
                    <AlertDialog>
                        <AlertDialogTrigger asChild>
                            <Button variant="ghost" size="icon" className="size-8 text-red-500">
                                <Trash className="size-4" />
                            </Button>
                        </AlertDialogTrigger>
                        <AlertDialogContent>
                            <AlertDialogHeader>
                                <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
                                <AlertDialogDescription>
                                    This action cannot be undone. This will permanently delete the user "{row.original.name}".
                                </AlertDialogDescription>
                            </AlertDialogHeader>
                            <AlertDialogFooter>
                                <AlertDialogCancel>Cancel</AlertDialogCancel>
                                <AlertDialogAction onClick={() => handleDeleteUser(row.original.id)} className="bg-red-600 hover:bg-red-700">
                                    Delete
                                </AlertDialogAction>
                            </AlertDialogFooter>
                        </AlertDialogContent>
                    </AlertDialog>
                </div>
            ),
        },
    ];

    return (
        <DataTable
            columns={columns}
            data={usersData.data}
            paginatedData={usersData}
            activeBulkActions={true}
            bulkDelete={{
                route: route('users.bulk-delete'),
                title: 'Delete Users',
                description: 'Are you sure you want to delete the selected users? This action cannot be undone.',
            }}
            tableKey="users-table"
        />
    );
};

🎨 Customization

Styling

The datatable uses Tailwind CSS classes and follows your existing design system. Key classes can be customized:

Table container: .rounded-md.border
Selected rows: data-state="selected"
Toolbar: .mb-3
Pagination: .mt-4

Search Behavior

The search is debounced by 500ms and triggers when:

Input length > 2 characters
Input is cleared (length = 0)

To customize the debounce timing, modify the useDebouncedCallback in datatable-toolbar.tsx:

const handleDebouncedSearch = useDebouncedCallback((value: string) => {
    // Search logic
}, 300); // Change from 500ms to 300ms

Column Visibility Persistence

Column visibility is automatically saved to localStorage using the tableKey prop. Each table should have a unique key:

<DataTable
    tableKey="users-table" // Unique identifier
    // ... other props
/>

Pagination Options

Default page size options are defined in datatable-pagination.tsx:

const PER_PAGE_OPTIONS = [10, 15, 20, 25, 30, 40, 50, 100];

🔧 Advanced Usage

Custom Search Logic

Extend the backend search to include more fields:

->when($request->search, function ($query, $search) {
    $query->where(function ($q) use ($search) {
        $q->where('name', 'like', '%' . $search . '%')
          ->orWhere('email', 'like', '%' . $search . '%')
          ->orWhere('phone', 'like', '%' . $search . '%')
          ->orWhereHas('profile', function ($profile) use ($search) {
              $profile->where('bio', 'like', '%' . $search . '%');
          });
    });
})

Advanced Sorting

Handle relationship sorting:

$allowedSorts = ['id', 'name', 'email', 'created_at', 'profile.company'];

if (in_array($queryParams['sort_by'], $allowedSorts)) {
    if (str_contains($queryParams['sort_by'], '.')) {
        // Handle relationship sorting
        [$relation, $field] = explode('.', $queryParams['sort_by']);
        $users->join($relation, 'users.id', '=', "{$relation}.user_id")
              ->orderBy("{$relation}.{$field}", $queryParams['sort_dir']);
    } else {
        $users->orderBy($queryParams['sort_by'], $queryParams['sort_dir']);
    }
}

Error Handling

Add error handling for failed requests:

// In your page component
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);

// Wrap router calls with error handling
const handleBulkAction = async (selectedRows: User[]) => {
    try {
        setLoading(true);
        setError(null);

        await router.delete(route('users.bulk-delete'), {
            data: { ids: selectedRows.map((row) => row.id) },
            onError: (errors) => {
                setError('Failed to delete users. Please try again.');
            },
        });
    } catch (err) {
        setError('An unexpected error occurred.');
    } finally {
        setLoading(false);
    }
};

🚀 Performance Tips

Use Resource Collections: Always use Laravel Resource Collections to control exactly what data is sent to the frontend
Limit Searchable Fields: Only search fields that are indexed in your database
Optimize Queries: Use select() to limit returned columns, eager load relationships
Debounced Search: The built-in 500ms debounce prevents excessive API calls
Column Visibility: Hidden columns still receive data - consider conditional inclusion in your Resource

🤝 Contributing

To extend the datatable functionality:

Add new features to the appropriate component
Update TypeScript interfaces in types/index.d.ts
Add backend support if needed
Update this documentation
Test with the Users example

📄 License

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

MIT License Summary

✅ Commercial use
✅ Modification
✅ Distribution
✅ Private use

❌ Liability
❌ Warranty

Built with ❤️ using React, TanStack Table, Laravel, and Inertia.js

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github/workflows		.github/workflows
app		app
bootstrap		bootstrap
config		config
database		database
public		public
resources		resources
routes		routes
screenshots		screenshots
storage		storage
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
artisan		artisan
components.json		components.json
composer.json		composer.json
composer.lock		composer.lock
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
phpunit.xml		phpunit.xml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

License

tarikulwebx/data-table

Folders and files

Latest commit

History

Repository files navigation