Download the PHP package developerawam/livewire-datatable without Composer

Laravel Livewire DataTable

A powerful and flexible DataTable component for Laravel Livewire that transforms your data into beautiful, interactive tables with zero configuration required.

🎯 Quick Overview

• Zero Configuration: Works out of the box with just your Eloquent model
• Server-Side Rendering: Handles thousands of records efficiently
• Feature-Rich: Search, sort, filter, paginate, and export with ease
• Fully Customizable: Configure every aspect via config or per-component
• Production Ready: Built for real-world applications with proper error handling

📚 Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Basic Usage
  • Columns
  • Searching
  • Sorting
  • Value Formatting
• Advanced Features
  • Relationships
  • Custom Query Scopes
  • Custom Cell Templates
  • Default Sort Configuration
  • Advanced Dynamic Filtering
  • Date Range Filter
• Exporting Data
  • Custom Export (Column Selection)
• Customization
  • Template System
  • Theme Configuration
  • Dynamic CSS Classes
  • Dark Mode Support
  • Pagination Options
  • Schema Cache
• API Integration
• Upgrading
• Troubleshooting
• Support

✨ Features

📋 Requirements

• PHP: ^8.2
• Laravel: ^12.0 || ^13.0
• Livewire: ^4.0
• CSS Framework: Tailwind CSS ^3.0+ OR Bootstrap 5+

Browser Support

All modern browsers (Chrome, Firefox, Safari, Edge)

📦 Installation

1. Install Package

2. Configure Your CSS Framework

For Tailwind CSS

For Tailwind CSS v3:

Add the package's views to your Tailwind configuration:

For Tailwind CSS v4+:

Use the @source directive in your resources/css/app.css:

This allows Tailwind CSS v4+ to automatically scan and generate styles for the datatable components.

For Bootstrap 5+

No additional configuration needed! Bootstrap is automatically detected and used.

3. (Optional) Publish Configuration

This allows you to customize default settings in config/livewire-datatable.php

4. (Optional) Set Template System

Choose your CSS framework template in .env:

5. (Optional) Configure Schema Cache

For production, schema introspection is cached to avoid repeated information_schema queries on every request:

Clear cache after migrations: php artisan cache:forget livewire-datatable:schema:* or call DataTable::clearSchemaCache().

6. (Optional) Configure Session Search

Advanced filter & global search persist automatically in the Laravel session (per table):

🚀 Quick Start

Create a fully functional DataTable in under 2 minutes.

1. Create Livewire Component

`

2. Setup Component

3. Create View

4. Use in Blade

Done! You now have a fully functional DataTable with search, sorting, and pagination.

📖 Basic Usage

Columns

Define what data to display and how to label it:

Searching

Make columns searchable:

Initial Search via Mount

Set an initial table search directly from mount — this populates the search input and filters the table immediately (search-only, not advanced filter):

The search mount param is table-specific (not advanced filter) and is session-persisted per table (DATATABLE_SESSION=true). Clearing the input clears the filter.

Sorting

Control which columns can be sorted:

Value Formatting

Format column values automatically using formatters.

Simple Formatters

Use simple string formatters for common formats:

Advanced Formatters

For complex formatting, use array syntax:

Available Formatters

Link Formatter

Render a column value as a clickable link, either to a named route (with parameters pulled from other columns) or to a custom/static URL.

Route with Column Parameters

If the route parameter name differs from the column name, use an associative array:

Custom / Static URL

You can also inject column values into a URL using {column} placeholders:

Options Reference

When exporting to Excel or PDF, link-formatted columns keep their original value (no URL).

Strip / HTML to String Formatter

Convert HTML content to plain string by stripping tags (replaces {!! !!} raw HTML with safe text):

� Advanced Features

Relationships

Display and sort data from related models using dot notation.

1. Setup Model with Relationships

2. Use Dot Notation in Columns

DataTable automatically handles relationships and makes them sortable!

Custom Query Scopes

Apply filters and constraints using Eloquent query scopes.

1. Define Scope on Model

2. Apply Scope to DataTable

3. Apply Scope with Parameters

Custom Cell Templates

Create rich, interactive cell content with custom Blade templates.

1. Define Custom Columns

2. Create Custom Templates

Status Badge (resources/views/components/table/status-badge.blade.php):

Action Buttons (resources/views/components/table/user-actions.blade.php):

3. Handle Events in Component

Available Variables in Custom Templates:

• $item - Current model instance
• $value - Current column value

Refresh Table After Actions:

Default Sort Configuration

Customize the default sort field and direction.

Works with relationships using dot notation:

Advanced Dynamic Filtering

Filter data across multiple columns with an intuitive interface.

Enable/Disable Filtering

How It Works

Users can:

• Click "Filter.." to add filter conditions
• Select columns to filter by
• Enter filter values
• Add multiple conditions (AND logic)
• Reset all filters at once

Customization

All filter elements have configurable CSS classes:

Session Persistence (Close ≠ Reset)

Advanced filter is now session-based: closing the panel (X / closeFilter) does not reset the filter. The filter remains active as a Laravel session per model + columns + scope, survives page reloads & navigation, and global search + advanced filter are combined with AND.

• Filter → Apply → filterDataSearch=true stored in session('livewire-datatable:filter:{md5}')
• Close (X) → only filter=false (panel hidden), filterDataSearch stays true
• Search → typing in the global search → session('...:search') updated, still AND-combined with the filter
• Reset → clearFilterSession() (clears filter & search session)

Manual clear: session()->forget('livewire-datatable:filter:...') — no need for php artisan cache:clear (session ≠ cache). The key is hashed from model|json(columns)|scope, so each table is isolated.

Date Range Filter

Filter your data by date ranges with a dedicated modal for date/datetime/timestamp columns.

How It Works

1. Click the calendar icon button in the table controls toolbar
2. A modal opens with:
   • Column selector — auto-populated with all date/datetime/timestamp columns from the main table and relationships
   • Start date and End date inputs
3. Select a column, pick your date range, and click Apply
4. An active filter badge appears showing the current date range
5. Click the × on the badge to reset the filter

Features

• Auto-detection: Scans database schema for date, datetime, and timestamp column types
• Relationship support: Date columns on related models are automatically detected (e.g., orders.created_at)
• Real-time validation: End date must be >= start date; shows inline error messages
• Export integration: Active date filter is applied when exporting to Excel or PDF (filename gets -date-filtered suffix)
• Compatible with advanced filters: Works alongside the existing advanced filter system

Configuration

Theme Classes (Tailwind)

All date filter elements are configurable in config/livewire-datatable.php under theme:

Bootstrap Configuration

Row Numbering ("no" Column)

The "no" column provides sequential row numbering that works intelligently with sorting and pagination.

Behavior

• Sequential numbering: Always displays 1, 2, 3... regardless of sort order
• Pagination-aware: Continues numbering across pages (page 2 shows 11, 12, 13...)
• Sort-independent: Doesn't reverse or change based on sort direction
• Consistent: Maintains the same numbering regardless of active filters or searches

Example

Even when sorting by different columns, the "no" column always displays sequential numbering.

🌐 API Integration

The DataTable supports both Eloquent models and API endpoints for flexibility.

Setup API DataTable

API View

Required Response Format

Your API must return:

API Query Parameters

DataTable sends these parameters:

Custom API Configuration

📤 Exporting Data

Export your DataTable data to Excel and PDF formats.

Export Features

• Export to Excel (.xlsx) and PDF
• Custom column selection via interactive modal
• Per-export paper size (A4, Letter, Legal) and orientation (Portrait, Landscape)
• Exports all records (respects pagination)
• Respects active search filters
• Respects active date range filter
• Maintains data formatting (dates, currency, etc.)
• Automatically excludes action columns
• Responsive UI with dark mode support

Configuration

Exclude behavior (export only, table display unaffected):

• Default exact: id, updated_at, deleted_at, password, remember_token (always excluded)
• exclude_columns (config) + excludeColumns mount param: exact match with dot notation (merged)
• exclude_patterns (config, default ['*_id']): Str::is() wildcard — automatically hides all *_id columns from custom export modal and file exports
• Mount param :excludeColumns="['api_token']" is merged (not replace) with defaults

How to Use

1. Click the "Export" dropdown in the controls
2. Select "Export Excel" or "Export PDF"
3. File downloads automatically

Example with Custom Options

Custom Export (Column Selection)

Choose exactly which columns to export and configure PDF output settings per-export.

How to Use

1. Click the Export dropdown in the table controls
2. Select Custom Export from the dropdown
3. A modal opens showing all available columns grouped by table
4. Select/deselect columns using checkboxes or the Select All / Deselect All buttons
5. Choose export type: Excel or PDF
6. For PDF: optionally choose Paper Size (A4, Letter, Legal) and Orientation (Portrait, Landscape)
7. Click Export — file downloads automatically

Smart Column Detection

The custom export modal automatically lists columns from:

• The main table's $columns definition
• All eager-loaded relationships ($with on the model)

Internal fields are excluded automatically: id, updated_at, deleted_at, password, remember_token.

Configuration

All custom export modal elements are themeable via config/livewire-datatable.php:

All keys have dark mode variants included by default.

🎨 Customization

Template System

The DataTable supports multiple CSS frameworks. Switch between them easily:

Available Templates

• tailwind - Tailwind CSS (default)
• bootstrap - Bootstrap 5+

Switch Template

Set in config/livewire-datatable.php:

Or in .env:

Bootstrap Pagination

If you're using Bootstrap CSS framework instead of Tailwind CSS, you can configure Livewire to use Bootstrap pagination styles. See the Livewire Bootstrap Pagination Documentation for detailed setup instructions.

Bootstrap Configuration

Theme Configuration

Customize the default appearance via config/livewire-datatable.php.

Quick Example

Per-Column Styling

Style specific columns using column keys:

Dynamic CSS Classes

Every element in the DataTable is fully configurable via CSS classes. All elements have data-class attributes for easy debugging.

Component-Level Overrides

Override theme for specific tables:

Use in view:

Dark Mode Support

Automatic dark mode support with Tailwind CSS. Simply add the dark class to your HTML element:

Or use dynamic switching:

Debugging Style Issues

Each element has a data-class attribute showing which config key controls it. Inspect in browser to find the right configuration option.

Pagination Options

Customize pagination behavior and options.

Per-Page Options

Configure available per-page choices:

The 'all' option allows users to display all records at once.

Default Per Page

Or let users choose with the per-page selector in the UI.

Schema Cache

Optimize production performance by caching schema introspection (Schema::getColumnListing / getColumnType).

The datatable introspects the database to auto-detect filterable, exportable, and date-filterable columns (including relations via $with). Without caching this triggers 100+ information_schema queries per request.

How It Works

• Results are cached per-table with Cache::remember() (key livewire-datatable:schema:{table}:columns)
• In-memory static cache avoids duplicate lookups within the same request
• TTL is configurable and defaults to 3600 seconds (1 hour)

Configuration

When to Clear

Clear after migrations that add/rename/drop columns:

Tip: In local development set DATATABLE_SCHEMA_CACHE_TTL=0 to always reflect fresh schema, in production keep 3600 or higher.

📝 Complete Example

Here's a comprehensive example with multiple features: 'export_dropdown_arrow' => '-mr-1 ml-2 h-5 w-5', 'export_button' => 'px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 dark:bg-blue-500 dark:hover:bg-blue-600 rounded-sm shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 dark:focus:ring-offset-gray-800',

    // Table structure
    'table_wrapper' => 'overflow-x-auto border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 shadow',
    'table' => 'min-w-full divide-y divide-gray-200 dark:divide-gray-700',

    // Table headers
    'thead' => '',
    'thead_row' => '',
    'th' => 'px-6 py-3 bg-gray-50 dark:bg-gray-700/50 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider',
    'th_sort_button' => 'group inline-flex items-center gap-x-2 hover:text-gray-700 dark:hover:text-gray-200',
    'th_sort_icon_wrapper' => 'inline-flex rounded p-1 transition',
    'th_sort_icon_active' => 'size-4 text-blue-500',
    'th_sort_icon_inactive' => 'size-4 text-gray-400 dark:text-gray-500 group-hover:text-gray-700 dark:group-hover:text-gray-200',
    'th_text' => 'text-gray-700 dark:text-gray-200 capitalize',

    // Table body
    'tbody' => 'divide-y divide-gray-200 dark:divide-gray-700',
    'tr' => 'hover:bg-gray-50 dark:hover:bg-gray-700/25 transition',
    'td' => 'px-6 py-4 whitespace-nowrap text-sm text-gray-700 dark:text-gray-200',

    // Empty state
    'empty_wrapper' => 'px-6 py-8 text-center',
    'empty_content' => 'flex flex-col items-center justify-center',
    'empty_icon' => 'size-16 text-gray-400 dark:text-gray-500 mb-2',
    'empty_text' => 'text-gray-500 dark:text-gray-400 text-sm font-medium',

    // Pagination
    'pagination_wrapper' => 'p-4',

    // Column-specific styling (optional)
    // 'td_id' => 'font-mono text-gray-500 text-xs',
    // 'td_email' => 'font-medium text-blue-600',
    // 'td_status' => 'text-center font-semibold',
    // 'td_actions' => 'text-right space-x-2',
]

];

env DATATABLE_SCHEMA_CACHE_TTL=3600 # 0 = disable (always hit DB, useful for local) bash php artisan config:clear

or

php artisan config:cache bash cp config/livewire-datatable.php config/livewire-datatable.php.bak php artisan vendor:publish --tag=livewire-datatable-config --force

re-apply your theme customizations from .bak

php artisan config:clear bash php artisan tinker --execute "echo config('livewire-datatable.schema_cache_ttl');"

should output 3600

> After migrations that add/rename columns, clear `php artisan cache:clear` or `DataTable::clearSchemaCache('users')`. On local set `DATATABLE_SCHEMA_CACHE_TTL=0`.

## ❓ Troubleshooting

### Common Issues

**Search not working on relationships**

Ensure the relationship is eager loaded in your model using `$with`:

**Custom columns not displaying**

- Verify the view file exists at the specified path
- Check that the view receives `$item` and `$value` variables

**Styles not applying**

- Verify Tailwind CSS is properly configured
- Check that package views are in `tailwind.config.js` content array

**Export not working**

- Verify export is enabled in config
- Check that required packages are installed

**Schema changes not showing (new columns missing in filter/export)**

- Schema is cached for `DATATABLE_SCHEMA_CACHE_TTL` seconds (default `3600`). Run `php artisan cache:clear` or `DataTable::clearSchemaCache('table_name')` after migrations, or set `DATATABLE_SCHEMA_CACHE_TTL=0` in local `.env`.

### Getting Help

1. Check [GitHub issues](https://github.com/developerawam/livewire-datatable/issues)
2. Review the examples in this documentation
3. Inspect browser console for errors

## 💝 Support

If this package has helped your project, consider supporting its continued development:

[![Donate on Saweria](https://img.shields.io/badge/Donate-Saweria-orange)](https://saweria.co/developerawam)

## 🔒 Security

Please report security vulnerabilities to [email protected] instead of using the public issue tracker.

## 👥 Credits

- [Developer Awam](https://github.com/developerawam) - Package Author
- [Restu](https://github.com/restu-lomboe) - Lead Developer

## 📄 License

Licensed under the MIT License - see [LICENSE.md](LICENSE.md) for details.

---

**Ready to build amazing DataTables?** [Get started now](#-quick-start) and transform your Laravel applications with beautiful, interactive tables!