Laravel Grid.js

What it solves

A data table over a large Eloquent query needs search, sort and pagination on the server, plus a data endpoint that must not let the browser choose which model or columns to read.

Writing that route, controller and JavaScript for every table is repetitive and easy to get wrong.

You build the grid from your own query in PHP and echo it in Blade. Grid.js fetches one page at a time from a built-in endpoint that only runs the query and columns sealed in an encrypted token, with no route, controller or JavaScript to write.

• Keeps your query: where clauses, scopes, joins, eager loads and default order
• Search (LIKE, relation columns included), sort and LIMIT/OFFSET pagination run in the database
• Encrypted grid token bound to the signed-in user or guest session and valid for 720 minutes; the endpoint never takes a model or column name from the browser
• Built-in date, datetime, number, currency, boolean and link formats, all escaped
• Action buttons with {id} URL placeholders; link formatters refuse javascript: URLs
• Grid.js 6.2.0 pinned on jsDelivr with SRI, or served from your public/ folder

Install

Requires PHP 8.3+ and Laravel 12 and 13.

composer require amjadiqbal/laravel-gridjs

Usage

use AmjadIqbal\GridJS\Facades\Grid;

$customers = Grid::fromQuery(Customer::active()->with('team'))
    ->columns(['name', 'email', ['field' => 'team.name', 'name' => 'Team']])
    ->searchable()
    ->sortable()
    ->pagination(10);

return view('customers.index', ['customers' => $customers]);

// In the view: {{ $customers }}

Setup

The service provider, the Grid facade and the data route register themselves. Optionally publish the config and choose CDN or local assets, or copy Grid.js into public/vendor/gridjs and set GRIDJS_CDN=false.

php artisan gridjs:install
php artisan gridjs:publish-assets

Columns

Per column: field, name, width, hidden, searchable, sortable, format and formatter. Accessors and casts work in cells but cannot be searched or sorted in SQL, so switch those off for them. Relation columns are searchable through whereHas but not sortable. A column marked hidden never leaves the server: its values are left out of the JSON, and it cannot be searched or sorted. The one exception is the key field of an actions() column, which is sent because the action links need it.

->columns([
    'name',
    'team.name',
    ['field' => 'email', 'name' => 'E-mail', 'width' => '240px'],
    ['field' => 'full_name', 'searchable' => false, 'sortable' => false],
    ['field' => 'mrr', 'name' => 'MRR', 'format' => ['type' => 'currency', 'currency' => 'USD']],
])

Search, sort, pagination and actions

The browser can only pick a page, a keyword and one of the sortable fields. A grid without pagination() returns at most gridjs.max_rows rows (1000). {id} in an action URL is filled from the key field.

->searchable(['name', 'email'], 200) // only these, 200 ms debounce
->sortable(['name', 'created_at'])
->pagination(25)
->actions([['label' => 'Edit', 'url' => '/customers/{id}/edit']])

Protecting the data

Every grid fetches from GET /gridjs/data. Add auth (or any middleware) in config/gridjs.php to keep it behind login. Each grid's token is encrypted with your APP_KEY and only works for whoever the page was rendered for: the signed-in user, or for guests a random value kept in their session. A token copied to another account or browser, a tampered token, or one older than token_lifetime minutes (720 by default) gets a 403, and an expired grid needs a page reload. Binding needs the session (the web middleware); set bind_tokens to false for a stateless setup. Rotating APP_KEY also invalidates open grids. A grid rendered with no signed-in user and no session (for example on a route without the web middleware) is not given a token at all: rendering it throws an exception telling you to add the web middleware. A token without a binding gets a 403 unless you set allow_unbound_tokens to true (false by default), which issues unbound tokens there instead; they still expire.

// config/gridjs.php
'middleware' => ['web', 'auth'],
'bind_tokens' => true,
'allow_unbound_tokens' => false,
'token_lifetime' => 720, // minutes

Assets and styling

• The first grid on a page prints the Grid.js script and theme plus a small mount script, once per request.
• Add @gridjsAssets to your layout's <head> to print them there, or set gridjs.assets.inject to false and load Grid.js yourself.
• With Vite::useCspNonce() the inline scripts get the nonce.
• ->theme('mermaid') is the default; ->theme(null) and ->className([...]) let you style it with Tailwind or your own CSS.
• Custom JavaScript formatters run as-is, so never build them from user input.

Support

Found a bug or want a feature? Open an issue on GitHub. For help adding it to your own project, use the quote form above.