Inertia.js Tables for Laravel Query Builder


This package provides a _DataTables-like_ experience for Inertia.js with support for searching, filtering, sorting, toggling columns, column reordering, column pinning, and pagination. It generates URLs that can be consumed by Spatie's excellent Laravel Query Builder package, with no additional logic needed. The components are styled with Tailwind CSS 3.0, but it's fully customizable with slots. The data refresh logic is based on Inertia's Ping CRM demo.

This package is a fork of [protonemedia/inertiajs-tables-laravel-query-builder], Since it has been abandonned in favor of a commercial project.

!Inertia.js Table for Laravel Query Builder

Features

- Fluent API: New intuitive API for single and multiple tables ✅ NEW!
- Infinite Scrolling: Automatic infinite scrolling with seamless data loading ✅ NEW!
- CSV Export: Automatic CSV export with all filtered data ✅ NEW!
- Number Filters: Advanced number filtering with multiple comparison operators ✅ NEW!
- Multiple Tables: Support for multiple independent tables in a single view ✅ NEW!
- Auto-fill: auto generates thead and tbody with support for custom cells
- Global Search
- Search per field
- Select filters
- Column Filters: Add filter icons directly in column headers for intuitive filtering
- Toggle columns
- Sort columns
- Column Reordering: Drag and drop columns to reorder them with persistent state ✅ NEW!
- Column Pinning: Pin important columns to prevent them from being hidden ✅ NEW!
- Pagination (support for Eloquent/API Resource/Simple/Cursor)
- Automatically updates the query string (by using Inertia's replace feature)
- Customizable header and body cells classes
- Custom row styling: Apply conditional CSS classes to table rows based on data
- Resizeable columns ✅

Compatibility

- Vue 3
- Laravel 11
- Inertia.js
- Tailwind CSS v3 + Forms plugin
- PHP 8.2+

Installation

You need to install both the server-side package and the client-side package. Note that this package is only compatible with Laravel 10, Vue 3.0, and requires the Tailwind Forms plugin.

$3

You can install the package via composer:

``bash
composer require adesin-fr/inertiajs-tables-laravel-query-builder
`

Fluent API ✨ NEW!

The package now provides a modern fluent API that makes table configuration more intuitive and powerful.

$3

For single table views, use the InertiaTable::make() method with a fluent syntax:

`php
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

// Method 1: Direct QueryBuilder with callback
return InertiaTable::make()
->withQueryBuilder(
QueryBuilder::for(User::class)
->allowedFilters([
AllowedFilter::partial('name'),
AllowedFilter::exact('status'),
NumberFilter::getQueryBuilderFilter('age'),
])
->allowedSorts(['name', 'email', 'created_at'])
->defaultSort('name')
)
->column('name', 'Name', sortable: true, searchable: true)
->column('email', 'Email', sortable: true, searchable: true)
->column('status', 'Status')
->column('age', 'Age', sortable: true)
->withGlobalSearch()
->selectFilter('status', [
'active' => 'Active',
'inactive' => 'Inactive',
])
->numberFilter('age', 'Age')
->render('Users/Index');

// Method 2: QueryBuilder callback (useful for multi-table setups)
return InertiaTable::make()
->withQueryBuilderCallback(function () {
return QueryBuilder::for(User::class)
->allowedFilters([
AllowedFilter::partial('name'),
AllowedFilter::exact('status'),
NumberFilter::getQueryBuilderFilter('age'),
])
->allowedSorts(['name', 'email', 'created_at'])
->defaultSort('name');
})
->column('name', 'Name', sortable: true, searchable: true)
->column('email', 'Email', sortable: true, searchable: true)
->withResource(\App\Http\Resources\UserResource::class) // Optional resource transformation
->render('Users/Index');
`

$3

For views with multiple tables, use the InertiaTable::view() method:

`php
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;

return InertiaTable::view('Dashboard/Index')
->table('users', function (InertiaTable $table) {
$table->withQueryBuilderCallback(function () {
// Configure query parameters for this table
InertiaTable::updateQueryBuilderParameters('users');

return QueryBuilder::for(User::class)
->allowedFilters([AllowedFilter::partial('name')])
->allowedSorts(['name', 'email'])
->defaultSort('name');
})
->column('name', 'Name', sortable: true, searchable: true)
->column('email', 'Email', sortable: true)
->withGlobalSearch()
->paginateMethod('paginate');
})
->table('products', function (InertiaTable $table) {
$table->withQueryBuilderCallback(function () {
// Configure query parameters for this table
InertiaTable::updateQueryBuilderParameters('products');

return QueryBuilder::for(Product::class)
->allowedFilters([
AllowedFilter::partial('title'),
NumberFilter::getQueryBuilderFilter('price')
])
->allowedSorts(['title', 'price'])
->defaultSort('title');
})
->column('title', 'Title', sortable: true, searchable: true)
->column('price', 'Price', sortable: true)
->numberFilter('price', 'Price')
->paginateMethod('simplePaginate');
})
->with(['customData' => 'Additional data for the view'])
->render();
`

$3

The fluent API provides many configuration options:

`php
return InertiaTable::make()
->name('custom-table') // Table name for multi-table setups
->pageName('customPage') // Custom pagination parameter name
->perPageOptions([10, 25, 50]) // Available per-page options
->defaultSort('created_at') // Default sorting column
->handleExport(true) // Enable/disable CSV export (default: true)
->paginateMethod('simplePaginate') // Pagination method
->withResource(\App\Http\Resources\UserResource::class) // Resource transformation
->with(['additional' => 'data']) // Additional data for the view
->render('Users/Index');
`

Traditional API (Legacy)

You can still use the traditional callbackF-based API if needed:

`php
return Inertia::render('Users/Index')->table(function (InertiaTable $table) {
$table->searchInput('name');
$table->selectFilter('status', ['active' => 'Active']);
});
`

Configuration

The package will automatically register the Service Provider which provides a table method you can use on an Interia Response.

$3

By default, the package will search for the routes/web.php file and check for a route with the "search" name. If you have different setup, you can define the route in your configuration file.

As described above, the package will detect if you use Spatie's Query Builder. This usually means the root you're using looks somewhat like this:

`php
$users = QueryBuilder::for(User::class)->paginate($request->perPage ?: 10);

return Inertia::render('Users/Index', [
'users' => $users
]);
`

#### Search fields

With the searchInput method, you can specify which attributes are searchable. Search queries are passed to the URL query as a filter. This integrates seamlessly with the filtering feature of the Laravel Query Builder package.

Though it's enough to pass in the column key, you may specify a custom label and default value.

`php
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;

Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->searchInput('name');

$table->searchInput(
key: 'framework',
label: 'Find your framework',
defaultValue: 'Laravel'
);
});
`

#### Select Filters

Select Filters are similar to search fields but use a select element instead of an input element. This way, you can present the user a predefined set of options. Under the hood, this uses the same filtering feature of the Laravel Query Builder package.

The selectFilter method requires two arguments: the key, and a key-value array with the options.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->selectFilter('language_code', [
'en' => 'Engels',
'nl' => 'Nederlands',
]);
});
`

The selectFilter will, by default, add a _no filter_ option to the array. You may disable this or specify a custom label for it.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->selectFilter(
key: 'language_code',
options: $languages,
label: 'Language',
defaultValue: 'nl',
noFilterOption: true,
noFilterOptionLabel: 'All languages'
);
});
`

#### Boolean Filters

This way, you can present the user a toggle. Under the hood, this uses the same filtering feature of the Laravel Query Builder package.

The toggleFilter method requires one argument: the key.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->toggleFilter('is_verified');
});
`

You can specify a custom label for it and a default value.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->toggleFilter(
key: 'is_verified',
label: 'Is email verified',
defaultValue: true,
);
});
`

#### Number range Filters

This way, you can present the user a toggle. Under the hood, this uses the same filtering feature of the Laravel Query Builder package.

The numberRangeFilter method requires two arguments: the key and the max value.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->numberRangeFilter('invoice_recall_count', 5);
});
`

You can specify a some other params.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->numberRangeFilter(
key: 'invoice_recall_count',
max: 5,
min: 0,
prefix: '',
suffix: '',
step: 1,
label: 'Invoice recall count',
defaultValue: [1,4],
);
});
`

You need to use a custom allowed filter for this filter.

`php
$users = QueryBuilder::for(/.../)
->allowedFilters([NumberRangeFilter::getQueryBuilderFilter('invoice_recall_count')]);
`

#### Number Filters ✨ NEW!

The numberFilter provides advanced comparison operations similar to date filters. You can filter by exact match, greater than, less than, between ranges, and more.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->numberFilter('age');
});
`

The Number Filter supports 6 different comparison operations:

- Exact: Find records with exact value
- Greater than: Find records greater than specified value
- Greater than or equal: Find records greater than or equal to specified value
- Less than: Find records less than specified value
- Less than or equal: Find records less than or equal to specified value
- Between: Find records within a specified range

You can customize the filter with additional parameters:

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->numberFilter(
key: 'age',
label: 'Filter by age',
defaultOperation: 'greater_than',
defaultValue: 18,
column_key: 'age' // Associate with a specific column
);
});
`

You need to use the custom NumberFilter for this filter:

`php
use AdesinFr\LaravelQueryBuilderInertiaJs\Filters\NumberFilter;

$users = QueryBuilder::for(User::class)
->allowedFilters([
NumberFilter::getQueryBuilderFilter('age')
]);
`

`php
$users = QueryBuilder::for(/.../)
->allowedFilters([NumberRangeFilter::getQueryBuilderFilter('invoice_recall_count')]);
`

#### Column Filters ✨ NEW!

You can now place filter icons directly in column headers for a more intuitive user experience. Each filter can be associated with a specific column using the column_key parameter.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->column('name', 'Name')
->column('status', 'Status')
->column('email', 'Email')
->column('created_at', 'Created');

// Associate a select filter with the 'status' column
$table->selectFilter(
key: 'status',
options: [
'active' => 'Active',
'inactive' => 'Inactive',
'pending' => 'Pending'
],
label: 'Status',
column_key: 'status' // 🎯 Associates the filter with the status column
);

// Associate a toggle filter with the 'email' column
$table->toggleFilter(
key: 'email_verified',
label: 'Email Verified',
column_key: 'email'
);

// Associate a number range filter with the 'created_at' column
$table->numberRangeFilter(
key: 'days_since_creation',
max: 365,
min: 0,
label: 'Days Since Creation',
column_key: 'created_at'
);
});
`

Features:

- 🎯 Visual Association: Filter icons appear directly in column headers
- 🎨 Active State Indicator: Icons change color when filters are applied
- 📱 Responsive Dropdown: Clean dropdown interface for filter options
- 🔄 Backward Compatible: Existing filters without column_key still work in the global filter bar

Benefits:

- More intuitive user experience
- Better visual organization
- Space-efficient interface
- Clear association between filters and data columns

For detailed examples and usage, see COLUMN_FILTERS.md.

#### Columns

With the column method, you can specify which columns you want to be toggleable, sortable, and searchable. You must pass in at least a key or label for each column.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->column('name', 'User Name');

$table->column(
key: 'name',
label: 'User Name',
canBeHidden: true,
hidden: false,
sortable: true,
searchable: true
headerClass: 'hidden md:table-cell', // This cell will be hidden on small screens
bodyClass: 'hidden md:table-cell', // This cell will be hidden on small screens
);
});
`

The searchable option is a shortcut to the searchInput method. The example below will essentially call $table->searchInput('name', 'User Name').

#### Global Search

You may enable Global Search with the withGlobalSearch method, and optionally specify a placeholder.

`php
Inertia::render('Page/Index')->table(function (InertiaTable $table) {
$table->withGlobalSearch();

$table->withGlobalSearch('Search through the data...');
});
`

If you want to enable Global Search for every table by default, you may use the static defaultGlobalSearch method, for example, in the AppServiceProvider class:

`php
InertiaTable::defaultGlobalSearch();
InertiaTable::defaultGlobalSearch('Default custom placeholder');
InertiaTable::defaultGlobalSearch(false); // disable
`

#### Example controller

Here are examples using both the new fluent API and the traditional API:

#### Fluent API Example (Recommended)

`php


namespace App\Http\Controllers;

use App\Models\User;
use App\Http\Resources\UserResource;
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;
use AdesinFr\LaravelQueryBuilderInertiaJs\Filters\NumberFilter;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

class UserIndexController
{
public function __invoke()
{
$globalSearch = AllowedFilter::callback('global', function ($query, $value) {
$query->where(function ($query) use ($value) {
Collection::wrap($value)->each(function ($value) use ($query) {
$query
->orWhere('name', 'LIKE', "%{$value}%")
->orWhere('email', 'LIKE', "%{$value}%");
});
});
});

return InertiaTable::make()
->withQueryBuilder(
QueryBuilder::for(User::class)
->defaultSort('name')
->allowedSorts(['name', 'email', 'created_at'])
->allowedFilters([
'name',
'email',
'status',
NumberFilter::getQueryBuilderFilter('age'),
$globalSearch
])
)
->withGlobalSearch()
->defaultSort('name')
->column('name', 'User Name', canBeHidden: false, sortable: true, searchable: true)
->column('email', 'Email Address', sortable: true, searchable: true)
->column('status', 'Status')
->column('age', 'Age', sortable: true)
->column('created_at', 'Created', sortable: true)
->column('actions', 'Actions', canBeHidden: false, sortable: false)
->selectFilter('status', [
'active' => 'Active',
'inactive' => 'Inactive',
'pending' => 'Pending'
])
->numberFilter('age', 'Filter by Age')
->withResource(UserResource::class)
->handleExport(true)
->render('Users/Index');
}
}
`

#### Traditional API Example (Legacy)

`php


namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Support\Collection;
use Inertia\Inertia;
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

class UserIndexController
{
public function __invoke()
{
$globalSearch = AllowedFilter::callback('global', function ($query, $value) {
$query->where(function ($query) use ($value) {
Collection::wrap($value)->each(function ($value) use ($query) {
$query
->orWhere('name', 'LIKE', "%{$value}%")
->orWhere('email', 'LIKE', "%{$value}%");
});
});
});

$users = QueryBuilder::for(User::class)
->defaultSort('name')
->allowedSorts(['name', 'email', 'language_code'])
->allowedFilters(['name', 'email', 'language_code', $globalSearch])
->paginate()
->withQueryString();

return Inertia::render('Users/Index', [
'users' => $users,
])->table(function (InertiaTable $table) {
$table
->withGlobalSearch()
->defaultSort('name')
->column(key: 'name', searchable: true, sortable: true, canBeHidden: false)
->column(key: 'email', searchable: true, sortable: true)
->column(key: 'language_code', label: 'Language')
->column(label: 'Actions')
->selectFilter(key: 'language_code', label: 'Language', options: [
'en' => 'English',
'nl' => 'Dutch',
]);
});
}
}
`

#### Column Reordering and Pinning ✨ NEW!

The table supports drag-and-drop column reordering with persistent state management. Users can reorder columns by dragging the column in the column list, and the new order is automatically saved and restored on future visits (persisted in brower's local storage)

##### Column Reordering

Columns can be reordered by dragging and dropping the column headers. The new column order is automatically persisted in the browser's local storage for each named table.

`php
// With the Fluent API
return InertiaTable::make()
->name('users-table') // Table name is required for persistent column ordering
->column('name', 'User Name', sortable: true)
->column('email', 'Email', sortable: true)
->column('status', 'Status')
->render('Users/Index');

// With the Traditional API
return Inertia::render('Users/Index')->table(function (InertiaTable $table) {
$table->column('name', 'User Name', sortable: true);
$table->column('email', 'Email', sortable: true);
$table->column('status', 'Status');
});
`

The column order is automatically saved per table name. If no table name is provided, the current route name is used as a fallback.

##### Column Pinning

Columns can be pinned (marked as non-hideable) to prevent users from accidentally hiding important columns. Pinned columns are marked with a "Fixed" label in the column toggle interface.

`php
// With the Fluent API
return InertiaTable::make()
->column('id', 'ID', canBeHidden: false) // This column is pinned and cannot be hidden
->column('name', 'User Name', canBeHidden: true, sortable: true)
->column('email', 'Email', canBeHidden: true, sortable: true)
->column('actions', 'Actions', canBeHidden: false) // Actions column is also pinned
->render('Users/Index');

// With the Traditional API
return Inertia::render('Users/Index')->table(function (InertiaTable $table) {
$table->column(key: 'id', label: 'ID', canBeHidden: false);
$table->column(key: 'name', label: 'User Name', canBeHidden: true, sortable: true);
$table->column(key: 'email', label: 'Email', canBeHidden: true, sortable: true);
$table->column(key: 'actions', label: 'Actions', canBeHidden: false);
});
`

##### Features of Column Management

- Persistent State: Column order and visibility are automatically saved in the browser's local storage
- Per-Table Configuration: Each named table maintains its own column configuration
- Drag & Drop Interface: Intuitive drag-and-drop interface for reordering columns
- Visual Feedback: Clear visual indicators during drag operations
- Reset Functionality: Users can reset columns to their default order and visibility
- Pinned Column Protection: Pinned columns cannot be hidden and are clearly marked in the UI

##### Frontend Usage

The column reordering and pinning features work automatically once you configure your columns on the backend. Users can:

1. Reorder Columns: Drag column headers to reorder them
2. Toggle Column Visibility: Use the column toggle button to show/hide columns
3. Reset Columns: Reset all columns to their default state
4. Pin Important Columns: Columns can be pinned. They will be always visible at left of the table !

The column state is automatically synchronized between the frontend and backend through the query string and local storage.

#### localStorage Persistence ✨ NEW!

The table component stores all customizations (column visibility, order, pinned state, and column widths) in the browser's localStorage. By default, the storage key is based on the table name, but you can customize it using the localStorageName prop.

##### Default Behavior

Without specifying localStorageName, the table uses table-{name} as the storage key:

`vue

`

##### Custom Storage Key

Use localStorageName to specify a custom key for localStorage:

`vue

`

##### Use Cases

- Multiple Instances: When using the same table component on different pages with different configurations
- User-Specific Settings: Combine with user ID for per-user preferences (e.g., user-123-products-table)
- Environment Separation: Separate settings between development and production
- Feature Flags: Different configurations for different feature variants

##### Storage Structure

The table stores two separate entries in localStorage:

| Key | Content |
| ------------------------------ | ------------------------------------------------ |
| {localStorageName}-columns | Column visibility, order, and pinned state |
| {localStorageName}-columnWidths | Column width preferences (when resizing is enabled) |

##### Reset Behavior

When the user clicks the "Reset" button, all customizations stored in localStorage for that table are cleared, and columns return to their default state.

$3

You can install the package via either npm or yarn:

`bash
npm install @adesin-fr/inertiajs-tables-laravel-query-builder --save

yarn add @adesin-fr/inertiajs-tables-laravel-query-builder
`

Add the repository path to the content array of your Tailwind configuration file. This ensures that the styling also works on production builds.

`js
module.exports = {
content: [
"./node_modules/@adesin-fr/inertiajs-tables-laravel-query-builder/*/.{js,vue}",
],
};
`

#### Default Stylesheet

The package now includes a default stylesheet that is automatically imported when you use the components. This provides a fully styled table out of the box without requiring Tailwind CSS classes.

The default styles use CSS variables, making it easy to customize the appearance of your tables.

##### Customizing the Default Styles

There are three ways to customize the default styles:

1. Override CSS Variables

The easiest way to customize the table appearance is by overriding CSS variables in your own CSS file:

`css
:root {
/ Change primary color to blue /
--ijt-color-primary: #3b82f6;
--ijt-color-primary-hover: #2563eb;
--ijt-color-primary-light: #dbeafe;

/ Change border radius /
--ijt-radius-md: 0.5rem;
--ijt-radius-lg: 0.75rem;

/ Change spacing /
--ijt-spacing-md: 1.25rem;
}
`

Available CSS Variables:

| Variable | Description | Default Value |
| ------------------------------ | -------------------------- | ------------------- |
| --ijt-color-primary | Primary accent color | #4f46e5 (indigo) |
| --ijt-color-primary-hover | Primary hover state | #4338ca |
| --ijt-color-primary-light | Light primary background | #e0e7ff |
| --ijt-color-success | Success color | #22c55e |
| --ijt-color-danger | Danger/error color | #ef4444 |
| --ijt-color-text | Main text color | #374151 |
| --ijt-color-text-light | Secondary text color | #6b7280 |
| --ijt-color-text-muted | Muted text color | #9ca3af |
| --ijt-color-bg | Background color | #ffffff |
| --ijt-color-bg-secondary | Secondary background | #f9fafb |
| --ijt-color-bg-hover | Hover background | #f3f4f6 |
| --ijt-color-border | Border color | #e5e7eb |
| --ijt-color-border-dark | Darker border color | #d1d5db |
| --ijt-radius-sm | Small border radius | 0.25rem |
| --ijt-radius-md | Medium border radius | 0.375rem |
| --ijt-radius-lg | Large border radius | 0.5rem |
| --ijt-spacing-xs | Extra small spacing | 0.25rem |
| --ijt-spacing-sm | Small spacing | 0.5rem |
| --ijt-spacing-md | Medium spacing | 1rem |
| --ijt-spacing-lg | Large spacing | 1.5rem |
| --ijt-shadow-sm | Small shadow | 0 1px 2px ... |
| --ijt-shadow-md | Medium shadow | 0 4px 6px ... |
| --ijt-font-size-sm | Small font size | 0.875rem |
| --ijt-font-size-base | Base font size | 1rem |

2. Override Specific Classes

You can override specific .ijt-* classes in your CSS:

`css
/ Custom table header styling /
.ijt-table__th {
background-color: #1e3a5f;
color: white;
}

/ Custom button styling /
.ijt-button {
background: linear-gradient(to right, #4f46e5, #7c3aed);
color: white;
border: none;
}

/ Custom pagination styling /
.ijt-pagination__button--active {
background-color: #4f46e5;
color: white;
}
`

3. Create Your Own Theme

For complete control, you can create your own theme file from scratch. Simply don't import the default styles and write your own CSS targeting the .ijt-* classes used by the components.

`js
// In your main.js, import components without the default styles
import {
Table,
Pagination,
// ... other components
} from "@adesin-fr/inertiajs-tables-laravel-query-builder";

// Then import your custom stylesheet
import "./styles/my-custom-table-theme.css";
`

##### Disabling Default Styles

If you prefer to use only Tailwind classes or your own styling system, you can prevent the default styles from being loaded by importing components individually without the main entry point, or by overriding the styles with higher specificity CSS rules.

#### Table component

To use the Table component and all its related features, you must import the Table component and pass the users data to the component.

`vue



`

The resource property automatically detects the data and additional pagination meta data. You may also pass this manually to the component with the data and meta properties:

`vue

`

If you want to manually render the table, like in v1 of this package, you may use the head and body slot. Additionally, you can still use the meta property to render the paginator.

`vue

`

The Table has some additional properties to tweak its front-end behaviour.

`vue

`

| Property | Description | Default |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| striped | Adds a _striped_ layout to the table. | false |
| preventOverlappingRequests | Cancels a previous visit on new user input to prevent an inconsistent state. | true |
| inputDebounceMs | Number of ms to wait before refreshing the table on user input. | 350 |
| preserveScroll | Configures the Scroll preservation behavior. You may also pass table-top to this property to scroll to the top of the table on new data. | false |
| hasCheckboxes | Enables row selection with checkboxes. Adds a checkbox column on the left side of the table with a "select all" checkbox in the header. Selected items are tracked via the __itSelected property. | false |
| rowClass | A function that receives the row item as parameter and returns a CSS class string to apply to the table row. Useful for conditional row styling. | null |
| paginationClickCallback | A function that receives the pagination URL as parameter and handles custom pagination logic instead of the default Inertia navigation. | null |
| localStorageName | Custom key for storing table customizations (column visibility, order, pinned state, and widths) in localStorage. If not provided, falls back to table-{name}. | null |

#### Custom Pagination Callback ✨ NEW!

You can now provide a custom callback function to handle pagination clicks instead of the default Inertia navigation. This is useful when you want to implement custom data loading logic, API calls, or state management for pagination.

`vue



`

Key Features:

- Full Control: Complete control over pagination behavior
- Async Support: Handle async operations like API calls
- Error Handling: Implement custom error handling and loading states
- State Management: Integrate with your preferred state management solution
- Backward Compatible: When not provided, falls back to default Inertia navigation
- URL Preservation: Receives the complete pagination URL with all filters and parameters

Use Cases:

- SPA Behavior: Implement single-page application pagination without page reloads
- API Integration: Fetch data from external APIs instead of server-side rendering
- Custom Loading States: Show custom loading indicators and animations
- State Persistence: Maintain complex application state during pagination
- Analytics Tracking: Track pagination interactions for analytics
- Performance Optimization: Implement custom caching or data optimization strategies

For a complete example, see examples/PaginationCallbackExample.vue.

#### Row Selection with Checkboxes

The hasCheckboxes property enables row selection with checkboxes. When enabled, a checkbox column is added on the left side of the table with a "select all" checkbox in the header.

`vue



`

Features:

- Select All: The header checkbox allows selecting/deselecting all visible rows at once
- Individual Selection: Each row has its own checkbox for individual selection
- Selection Tracking: Selected items are tracked via the __itSelected property on each item
- Selection Event: The selectionChanged event is emitted whenever the selection changes, providing the array of selected items
- Selection Counter: A label displays the number of selected lines (e.g., "3 line(s) selected")

Use Cases:

- Bulk operations (delete, export, status change)
- Multi-select for batch processing
- Comparison between multiple items

The Table has some events that you can use

- rowClicked: this event is fired when the user click on the row. The event give you this informations: event, item, key.
Be careful if you use this event with a clickable element inside the row like an action button.
Don't forget to use event.stopPropagation() for all other clickable elements.
If you want to disable rowClicked events on your "actions" column, you can use the key argument to filter out the event when the key corresponds to your action column key.

#### Custom row styling

You can apply custom CSS classes to table rows based on the row data using the rowClass property. This function receives the row item as a parameter and should return a CSS class string.

`vue



`

For more advanced examples of custom row styling, see examples/RowClassExamples.vue.

#### Custom column cells

When using _auto-fill_, you may want to transform the presented data for a specific column while leaving the other columns untouched. For this, you may use a cell template. This example is taken from the Example Controller above.

`vue

`

#### Custom header cells

When using _auto-fill_, you may want to transform the presented data for a specific header while leaving the other columns untouched. For this, you may use a header template. This example is taken from the Example Controller above.

`vue

`

#### Multiple tables per page

You may want to use more than one table component per page. The new fluent API makes this much easier with the InertiaTable::view() method.

#### Using the New Fluent API (Recommended)

`php
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

return InertiaTable::view('TwoTables')
->table('companies', function (InertiaTable $table) {
$table->withQueryBuilderCallback(function () {
// Update query parameters for this table
InertiaTable::updateQueryBuilderParameters('companies');

return QueryBuilder::for(Company::class)
->defaultSort('name')
->allowedSorts(['name', 'email'])
->allowedFilters(['name', 'email']);
})
->pageName('companiesPage')
->column('name', 'Company Name', searchable: true, sortable: true)
->column('email', 'Contact Email', searchable: true, sortable: true)
->column('address', 'Address', searchable: true)
->withGlobalSearch()
->defaultSort('name');
})
->table('users', function (InertiaTable $table) {
$table->withQueryBuilderCallback(function () {
// Update query parameters for this table
InertiaTable::updateQueryBuilderParameters('users');

return QueryBuilder::for(User::class)
->defaultSort('name')
->allowedSorts(['name', 'email'])
->allowedFilters(['name', 'email']);
})
->pageName('usersPage')
->column('name', 'User Name', searchable: true, sortable: true)
->column('email', 'User Email', searchable: true, sortable: true)
->withGlobalSearch()
->defaultSort('name');
})
->render();
`

#### Using the Traditional API (Legacy)

You may want to use more than one table component per page. Displaying the data is easy, but using features like filtering, sorting, and pagination requires a slightly different setup. For example, by default, the page query key is used for paginating the data set, but now you want two different keys for each table. Luckily, this package takes care of that and even provides a helper method to support Spatie's query package. To get this to work, you need to _name_ your tables.

Let's take a look at Spatie's QueryBuilder. In this example, there's a table for the companies and a table for the users. We name the tables accordingly. So first, call the static updateQueryBuilderParameters method to tell the package to use a different set of query parameters. Now, filter becomes companies_filter, column becomes companies_column, and so forth. Secondly, change the pageName of the database paginator.

`php
InertiaTable::updateQueryBuilderParameters('companies');

$companies = QueryBuilder::for(Company::query())
->defaultSort('name')
->allowedSorts(['name', 'email'])
->allowedFilters(['name', 'email'])
->paginate(pageName: 'companiesPage')
->withQueryString();

InertiaTable::updateQueryBuilderParameters('users');

$users = QueryBuilder::for(User::query())
->defaultSort('name')
->allowedSorts(['name', 'email'])
->allowedFilters(['name', 'email'])
->paginate(pageName: 'usersPage')
->withQueryString();
`

Then, we need to apply these two changes to the InertiaTable class. There's a name and pageName method to do so.

`php
return Inertia::render('TwoTables', [
'companies' => $companies,
'users' => $users,
])->table(function (InertiaTable $inertiaTable) {
$inertiaTable
->name('users')
->pageName('usersPage')
->defaultSort('name')
->column(key: 'name', searchable: true)
->column(key: 'email', searchable: true);
})->table(function (InertiaTable $inertiaTable) {
$inertiaTable
->name('companies')
->pageName('companiesPage')
->defaultSort('name')
->column(key: 'name', searchable: true)
->column(key: 'address', searchable: true);
});
`

Lastly, pass the correct name property to each table in the Vue template. Optionally, you may set the preserve-scroll property to table-top. This makes sure to scroll to the top of the table on new data. For example, when changing the page of the _second_ table, you want to scroll to the top of the table, instead of the top of the page.

`vue



`

#### Pagination translations

You can override the default pagination translations with the setTranslations method. You can do this in your main JavaScript file:

`js
import { setTranslations } from "@adesin-fr/inertiajs-tables-laravel-query-builder";

setTranslations({
// Pagination translations
next: "Next",
no_results_found: "No results found",
of: "of",
per_page: "per page",
previous: "Previous",
results: "results",
to: "to",

// General UI translations
reset: "Reset",
search: "Search...",
noLineSelected: "No line selected",
lineSelected: "line(s) selected",

// Date filter translations
filter_type: "Filter type",
no_filter: "No filter",
exact_date: "Exact date",
before_date: "Before",
after_date: "After",
date_range: "Date range",
start_date: "Start date",
end_date: "End date",
reset_filter: "Reset filter",

// Number filter translations
exact_number: "Exact value",
less_than: "Less than",
greater_than: "Greater than",
less_than_or_equal: "Less than or equal",
greater_than_or_equal: "Greater than or equal",
number_range: "Between",
start_number: "Start value",
end_number: "End value",

// Export and menu translations
export_csv: "Export CSV",
add_search_fields: "Add search field",
show_hide_columns: "Show / Hide columns",
grouped_reset: "Reset",
});
`

Available Translation Keys:

| Key | Description | Default Value |
| ----------------------- | ------------------------------------ | ----------------------- |
| next | Next button in pagination | "Next" |
| previous | Previous button in pagination | "Previous" |
| no_results_found | Message when no data | "No results found" |
| of | Pagination separator (X of Y) | "of" |
| per_page | Per page selector suffix | "per page" |
| results | Results count label | "results" |
| to | Range separator (X to Y) | "to" |
| reset | Reset button label | "Reset" |
| search | Search input placeholder | "Search..." |
| noLineSelected | Bulk action message | "No line selected" |
| lineSelected | Bulk action message | "line(s) selected" |
| filter_type | Filter type dropdown label | "Filter type" |
| no_filter | No filter option | "No filter" |
| exact_date | Date filter: exact match | "Exact date" |
| before_date | Date filter: before date | "Before" |
| after_date | Date filter: after date | "After" |
| date_range | Date filter: date range | "Date range" |
| start_date | Date filter: start date | "Start date" |
| end_date | Date filter: end date | "End date" |
| reset_filter | Reset filter button | "Reset filter" |
| exact_number | Number filter: exact value | "Exact value" |
| less_than | Number filter: less than | "Less than" |
| greater_than | Number filter: greater than | "Greater than" |
| less_than_or_equal | Number filter: less than or equal | "Less than or equal" |
| greater_than_or_equal | Number filter: greater than or equal | "Greater than or equal" |
| number_range | Number filter: between range | "Between" |
| start_number | Number filter: start value | "Start value" |
| end_number | Number filter: end value | "End value" |
| export_csv | CSV export button | "Export CSV" |
| add_search_fields | Add search field button | "Add search field" |
| show_hide_columns | Column visibility button | "Show / Hide columns" |
| grouped_reset | Grouped actions reset | "Reset" |

#### Table.vue slots

The Table.vue has several slots that you can use to inject your own implementations.

| Slot | Description |
| ----------------- | -------------------------------------------------------------------------------------- |
| table | The actual table element. |
| tableColumns | The location of the button + dropdown to toggle columns. |
| tableFilter | The location of the button + dropdown to select filters. |
| tableGlobalSearch | The location of the input element that handles the global search. |
| tableReset | The location of the button that resets the table. |
| tableAddSearchRow | The location of the button + dropdown to add additional search rows. |
| tableSearchRows | The location of the input elements that handle the additional search rows. |
| tableWrapper | The component that _wraps_ the table element, handling overflow, shadow, padding, etc. |
| head | The location of the table header. |
| body | The location of the table body. |
| exportButton | The CSV export button. Provides exportUrl and translations as slot props. |
| with-grouped-menu | Use the grouped menu instead of multiple buttons |
| pagination | The location of the paginator. |
| tableSummary | A slot below the table for totals/summary. Provides data, meta, and selectedItems as slot props. Works with lazy-loaded data. |
| color | The style of the table |

Each slot is provided with props to interact with the parent Table component.

`vue

`

#### Table Summary Slot

The tableSummary slot allows you to add a summary section below the table (e.g., totals, averages, or any aggregated data). This slot receives all loaded data, including items loaded via infinite scrolling (lazy loading).

`vue



`

Slot Props:

| Prop | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------------------ |
| data | Array | All currently loaded table data (includes lazy-loaded items when using infinite scrolling) |
| meta | Object | Pagination metadata (total, current_page, per_page, etc.) |
| selectedItems | Array | Array of currently selected items (when hasCheckboxes is enabled) |

Use Cases:

- Totals Row: Display sum of numeric columns (amounts, quantities, etc.)
- Averages: Show average values across all loaded data
- Selection Summary: Display aggregated info about selected rows
- Statistics: Show min/max values, counts, or other statistics
- Infinite Scrolling Support: Works seamlessly with lazy-loaded data, updating as more items are loaded

#### Customizing the Export Button

The exportButton slot allows you to customize the CSV export functionality with your own button design and behavior:

`vue



`

You can also create more complex export options:

`vue

`

$3

You can customize some parts of the table.

Provide an object with the desired customizations in app.js file like this:

`javascript
const themeVariables = {
inertia_table: {
per_page_selector: {
select: {
primary: "your classes",
},
},
},
};

createInertiaApp({
progress: {
color: "#4B5563",
},
title: (title) => ${title} - ${appName},
resolve: (name) =>
resolvePageComponent(
./Pages/${name}.vue,
import.meta.glob("./Pages/*/.vue"),
),
setup({ el, App, props, plugin }) {
return (
createApp({ render: () => h(App, props) })
// ...
.provide("themeVariables", themeVariables)
// ...
.mount(el)
);
},
});
`

You can customize the default style by overiding the default style like that:

`javascript
const themeVariables = {
inertia_table: {
per_page_selector: {
select: {
base: "block min-w-max shadow-sm text-sm rounded-md",
color: {
primary:
"border-gray-300 focus:ring-yellow-500 focus:border-yellow-500",
},
},
},
},
};
`

Or you can create a new style and using the color prop on the Table.vue

`javascript
const themeVariables = {
inertia_table: {
select: {
base: "block min-w-max shadow-sm text-sm rounded-md",
color: {
red_style:
"border-gray-300 focus:ring-red-500 focus:border-red-500",
},
},
},
};
`

`vue

`

Available customizations

`javascript
const themeVariables = {
inertia_table: {
button_with_dropdown: {
button: {
base: "w-full border rounded-md shadow-sm px-4 py-2 inline-flex justify-center text-sm font-medium focus:outline-none focus:ring-2 focus:ring-offset-2",
color: {
primary: "bg-white text-gray-700 hover:bg-gray-50 border-gray-300 focus:ring-indigo-500",
dootix: "bg-white text-gray-700 hover:bg-gray-50 border-gray-300 focus:ring-cyan-500",
},
},
},
per_page_selector: {
select: {
base: "block min-w-max shadow-sm text-sm rounded-md",
color: {
primary: "border-gray-300 focus:ring-indigo-500 focus:border-indigo-500",
dootix: "border-gray-300 focus:ring-cyan-500 focus:border-blue-500",
},
},
},
table_filter: {
select_filter: {
select: {
base: "block w-full shadow-sm text-sm rounded-md",
color: {
primary: "border-gray-300 focus:ring-indigo-500 focus:border-indigo-500",
dootix: "border-gray-300 focus:ring-cyan-500 focus:border-blue-500",
},
},
},
toggle_filter: {
toggle: {
base: "w-11 h-6 rounded-full after:border after:rounded-full after:h-5 after:w-5",
color: {
primary: "after:bg-white after:border-white peer-checked:bg-indigo-500 bg-red-500",
dootix: "after:bg-white after:border-white peer-checked:bg-gradient-to-r peer-checked:from-cyan-500 peer-checked:to-blue-600 bg-red-500",
disabled: "after:bg-white after:border-white bg-gray-200",
}
},
reset_button: {
base: "rounded-md focus:outline-none focus:ring-2 focus:ring-offset-2",
color: {
primary: "text-gray-400 hover:text-gray-500 focus:ring-indigo-500",
dootix: "text-gray-400 hover:text-gray-500 focus:ring-cyan-500",
},
},
number_range_filter: {
main_bar: {
base: "h-2 rounded-full",
color: {
primary: "bg-gray-200",
dootix: "bg-gray-200",
},
},
selected_bar: {
base: "h-2 rounded-full",
color: {
primary: "bg-indigo-600",
dootix: "bg-gradient-to-r from-cyan-500 to-blue-600",
},
},
button: {
base: "h-4 w-4 rounded-full shadow border",
color: {
primary: "bg-white border-gray-300",
dootix: "bg-white border-gray-300",
},
},
popover: {
base: "truncate text-xs rounded py-1 px-4",
color: {
primary: "bg-gray-600 text-white",
dootix: "bg-gray-600 text-white",
},
},
popover_arrow: {
color: {
primary: "text-gray-600",
dootix: "text-gray-600",
},
},
text: {
color: {
primary: "text-gray-700",
dootix: "text-gray-700",
},
},
global_search: {
base: "block w-full pl-9 text-sm rounded-md shadow-sm",
color: {
primary: "focus:ring-indigo-500 focus:border-indigo-500 border-gray-300",
dootix: "focus:ring-cyan-500 focus:border-blue-500 border-gray-300",
},
},
reset_button: {
base: "w-full border rounded-md shadow-sm px-4 py-2 inline-flex justify-center text-sm font-medium focus:outline-none focus:ring-2 focus:ring-offset-2",
color: {
primary: "bg-white text-gray-700 hover:bg-gray-50 border-gray-300 focus:ring-indigo-500",
dootix: "bg-white text-gray-700 hover:bg-gray-50 border-gray-300 focus:ring-cyan-500",
},
},
table_search_rows: {
input: {
base: "flex-1 min-w-0 block w-full px-3 py-2 rounded-none rounded-r-md text-sm",
color: {
primary: "border-gray-300 focus:ring-indigo-500 focus:border-indigo-500",
dootix: "border-gray-300 focus:ring-cyan-500 focus:border-blue-500",
},
},
remove_button: {
base: "rounded-md focus:outline-none focus:ring-2 focus:ring-offset-2",
color: {
primary: "text-gray-400 hover:text-gray-500 focus:ring-indigo-500",
dootix: "text-gray-400 hover:text-gray-500 focus:ring-cyan-500",
},
},
},
},
}
`

Infinite Scrolling ✨ NEW!

The package now supports infinite scrolling, allowing you to load data progressively as the user scrolls down the table. This provides a seamless experience for large datasets without traditional pagination.

$3

Simply call ->withInfiniteScrolling() before ->render():

``php
use AdesinFr\LaravelQueryBuilderInertiaJs\InertiaTable;
use Spatie\QueryBuilder\QueryBuilder;

return InertiaTable::make()
->name('users')
->column('id', 'ID', sortable: true)
->column('name', 'Name', sortable: true, searchable: true)
->column('email', 'Email', sortable: true, searchable: true)
->column('created_at', 'Created At', sortable: true)
->withGlobalSearch('Search users...')
->defaultSort('-created_at')
->perPageOptions([15, 30, 50, 100])
->withQueryBuilder(
QueryBuilder::for(User::class)
->allowedFilters(['name', 'email'])
->allowedSorts(['name', 'email', 'created_at'])