Download the PHP package adesin-fr/inertiajs-tables-laravel-query-builder without Composer
On this page you can find all versions of the php package adesin-fr/inertiajs-tables-laravel-query-builder. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download adesin-fr/inertiajs-tables-laravel-query-builder
More information about adesin-fr/inertiajs-tables-laravel-query-builder
Files in adesin-fr/inertiajs-tables-laravel-query-builder
Package inertiajs-tables-laravel-query-builder
Short Description Inertia.js Front-end Components for Spatie's Laravel Query Builder
License MIT
Homepage https://github.com/Adesin-Fr/inertiajs-tables-laravel-query-builder
Informations about the package inertiajs-tables-laravel-query-builder
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.
Features
- Fluent API: New intuitive API for single and multiple tables ✅ 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
andtbody
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.
Server-side installation (Laravel)
You can install the package via composer:
Fluent API ✨ NEW!
The package now provides a modern fluent API that makes table configuration more intuitive and powerful.
Single Table
For single table views, use the InertiaTable::make()
method with a fluent syntax:
Multiple Tables
For views with multiple tables, use the InertiaTable::view()
method:
Additional Fluent API Methods
The fluent API provides many configuration options:
Traditional API (Legacy)
You can still use the traditional callback-based API if needed:
Configuration
The package will automatically register the Service Provider which provides a table
method you can use on an Interia Response.
Getting started with Traditional API
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:
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.
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.
The selectFilter
will, by default, add a no filter option to the array. You may disable this or specify a custom label for it.
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.
You can specify a custom label for it and a default value.
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.
You can specify a some other params.
You need to use a custom allowed filter for this filter.
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.
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:
You need to use the custom NumberFilter for this filter:
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.
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.
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.
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:
Example controller
Here are examples using both the new fluent API and the traditional API:
Fluent API Example (Recommended)
Traditional API Example (Legacy)
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.
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.
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:
- Reorder Columns: Drag column headers to reorder them
- Toggle Column Visibility: Use the column toggle button to show/hide columns
- Reset Columns: Reset all columns to their default state
- 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.
Client-side installation (Inertia)
You can install the package via either npm
or yarn
:
Add the repository path to the content
array of your Tailwind configuration file. This ensures that the styling also works on production builds.
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.
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:
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.
The Table
has some additional properties to tweak its front-end behaviour.
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 |
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 |
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.
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.
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.
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.
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.
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)
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.
Then, we need to apply these two changes to the InertiaTable
class. There's a name
and pageName
method to do so.
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.
Pagination translations
You can override the default pagination translations with the setTranslations
method. You can do this in your main JavaScript file:
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. |
color | The style of the table |
Each slot is provided with props to interact with the parent Table
component.
Customizing the Export Button
The exportButton
slot allows you to customize the CSV export functionality with your own button design and behavior:
You can also create more complex export options:
Customizations available
You can customize some parts of the table.
Provide an object with the desired customizations in app.js
file like this:
You can customize the default style by overiding the default style like that:
Or you can create a new style and using the color
prop on the Table.vue
Available customizations
CSV Export ✨ NEW!
The package now includes a powerful CSV export feature that automatically exports all filtered data, not just the current page.
Automatic CSV Export
CSV export is automatically enabled for all tables. An export button will appear in the table interface, and the export URL automatically includes all current filters and search parameters.
Single Table Export
Multiple Table Export
When using multiple tables, each table gets its own export button with the appropriate table identifier:
Disabling CSV Export
If you want to disable CSV export for a specific table:
CSV Export Features
- Complete Data Export: Exports all filtered data, not just the current page
- Automatic Filtering: Export URLs automatically include all active filters and search parameters
- UTF-8 Support: Proper encoding with BOM for international characters
- Reactive URLs: Export URLs update automatically when filters change
- Multiple Tables: Each table in multi-table views has its own export functionality
- Proper CSV Formatting: Automatic escaping of special characters and proper quoting
- Column Visibility: Only exports visible columns (respects column hiding)
- Smart Data Formatting: Automatic formatting for dates, booleans, and other data types
How It Works
- Automatic Route Handling: The package automatically detects CSV export requests via the
do_export=1
query parameter - Filter Preservation: All current filters, searches, and sorting are automatically applied to the export
- Complete Dataset: The export bypasses pagination to include all matching records
- Proper Headers: CSV files are served with appropriate headers and UTF-8 encoding
- Filename Generation: Automatic filename generation with table name and timestamp
Frontend Integration
The CSV export button is automatically added to the table interface. The export URL is reactive and updates automatically when filters change:
The export functionality is built into the Table.vue
component and requires no additional configuration.
Custom Export Callbacks ✨ NEW!
You can now provide a custom callback function to handle exports manually. This allows you to customize the export format, apply additional processing, or export to different formats like Excel or JSON.
Basic Custom Export
Export to Different Formats
Integration with Laravel Excel
Custom Export Service
Key Features of Custom Export Callbacks:
- Full Control: Complete control over export format and processing
- QueryBuilder Access: Receive the QueryBuilder with all filters and searches applied
- Multiple Formats: Export to CSV, Excel, JSON, PDF, or any custom format
- Data Processing: Apply custom transformations and formatting before export
- Service Integration: Easily integrate with existing export services or packages
- Preserves Filters: All table filters, searches, and sorting are automatically applied to the QueryBuilder
The custom export callback completely replaces the default CSV export behavior when defined, giving you full flexibility over the export process.
Testing
A huge Laravel Dusk E2E test-suite can be found in the app
directory. Here you'll find a Laravel + Inertia application.
Upgrading from v1
Server-side
- The
addColumn
method has been renamed tocolumn
. - The
addFilter
method has been renamed toselectFilter
. - The
addSearch
method has been renamed tosearchInput
. - For all renamed methods, check out the arguments as some have been changed.
- The
addColumns
andaddSearchRows
methods have been removed. - Global Search is not enabled by default anymore.
Client-side
- The
InteractsWithQueryBuilder
mixin has been removed and is no longer needed. - The
Table
component no longer needs thefilters
,search
,columns
, andon-update
properties. - When using a custom
thead
ortbody
slot, you need to provide the styling manually. - When using a custom
thead
, theshowColumn
method has been renamed toshow
. - The
setTranslations
method is no longer part of thePagination
component, but should be imported. - The templates and logic of the components are not separated anymore. Use slots to inject your own implementations.
Examples
The examples/
folder contains comprehensive usage examples:
- SimpleRowClassExample.vue: Quick example showing basic usage of the
rowClass
property - ExportButtonExamples.vue: Complete examples of custom CSV export buttons with different styles and functionalities
- RowClassExamples.vue: Advanced examples of custom row styling using the
rowClass
property - PaginationCallbackExample.vue: Complete example demonstrating custom pagination handling with the
paginationClickCallback
property
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
- Pascal Baljet
- All Contributors
- Ludovic LEMARINEL
License
The MIT License (MIT). Please see License File for more information.