Download the PHP package ivanharmat/crewgrid without Composer

CrewGrid

A server-driven Livewire data grid for Laravel — sorting, per-column filters, quick search, pagination or infinite loading, and shareable URL state. Themeable markup with Bootstrap 3 support, for the many production apps that modern grid packages have left behind.

Born out of replacing a legacy Kendo UI grid system in a large Laravel app; extracted as a package so any Laravel/Livewire project can use it.

Why CrewGrid?

• Server-side everything — filtering, sorting and pagination run in the database, so a grid over a 2M-row table behaves the same as one over 200 rows.
• Bootstrap 3 theme out of the box — legacy AdminLTE/Bootstrap 3 apps get a modern Livewire grid without a frontend rewrite. (Tailwind and Bootstrap 5 themes are on the roadmap.)
• Kendo-style filter popovers — a funnel icon on each filterable column opens a text, checkbox-list or date-range filter; active filters are highlighted.
• Shareable URLs — sort, filters, search and page live in the query string, so a filtered view can be bookmarked or sent to a coworker.
• Plain Blade cells — no JavaScript row templates; format cells with closures or render them with your own Blade views.

Requirements

Installation

The service provider is auto-discovered. Optionally publish the config or views:

Quick start

Create a Livewire component extending CrewGrid\Grid and describe your grid with a query and columns:

Drop it on any page:

That's it — sorting, filtering, quick search, pagination and URL state all work.

Column API

All default filter behaviors have callback escape hatches, so computed columns, joins and cross-database filters are all expressible.

Appearance, column widths and show/hide

Column borders and row lines are on by default; turn them off app-wide with 'bordered' => false in the config, or per grid with public ?bool $bordered = false;.

Resizing. Every column is resizable unless you call ->notResizable(). Drag the divider in the header; a Reset Widths button appears once anything has been dragged. Columns without an explicit ->width() keep whatever the browser lays out naturally — the grid freezes those widths at the moment a drag starts and only then switches to a fixed layout, so nothing snaps to equal widths. config('crewgrid.min_column_width') (default 60) is the floor.

Show/hide. The Columns button in the toolbar lists every column with a checkbox, badges how many are hidden, and offers Show All. The last visible column can't be hidden. Filters and quick search always run over the full column set — hiding a column changes the view, not the result set — so a filter left on a hidden column keeps applying and is flagged with a funnel in the picker rather than silently shrinking the results.

Where preferences live. These are server-side, kept in the session under preferenceKey(), so they survive a reload with no flash of unstyled columns and the <colgroup> can be rendered correctly on the server. Widths and hidden columns deliberately stay out of the query string: sorting and filtering describe what you are looking at and are worth sharing, while those two are personal viewing preferences that would only make shared links noisy. Override loadPreferences() / savePreferences() to store them per user instead and they will outlive the session:

No build step and nothing to add to your layout — the small stylesheet and resize script are emitted inline once per page.

Remembered view

A grid comes back to the sort, filters, quick search and page size its user left it on, stored alongside the widths and hidden columns — so the same loadPreferences() override decides how long that lasts.

A value named in the URL wins over the stored one and replaces it, so a link someone was sent shows what it says and is where they pick up from, while a bare address returns to whatever they last had on screen. The page number is never remembered — coming back on page 47 of a list is disorienting in a way that coming back to the filters that produced it is not.

A grid with a mount() of its own must call parent::mount(), which is what restores the view; defaults it sets afterwards only apply when there was nothing to restore:

A grid that seeds a starting filter should ask viewWasRestored() first, or a user who clears that filter is handed it back on their next visit:

A grid with state of its own — a scope its toolbar control sets, say — adds it by name, paired with the query string parameter it travels under. Mark that property #[Url] too, which is what puts the value in the address and reads it back:

Row classes

Colour or mark whole rows by overriding rowClass() on the grid — it returns CSS classes for the <tr>, so the page owns its palette:

Toolbar controls

Some filters belong to the whole grid rather than to one column — an office picker, a date scope, active / archived / deleted. Point toolbarView() at a view and it renders in the toolbar, beside the quick search:

The view renders inside the component, so it binds public properties with wire:model.live and reads $this like the rest of the grid. Scope the query on that property in query() and the whole grid — paging, sorting, the Excel export — follows it.

Pager position

The pager row renders below the table by default; put it above, or at both ends for long pages:

Loading modes

Set per grid. Page size comes from config('crewgrid.per_page'), with a per-page picker driven by per_page_options.

Theming

Markup is rendered from crewgrid::themes.{theme} Blade views. Set the theme app-wide in config, or per grid with public ?string $theme = 'bootstrap5';. Publish the views to override any markup. An unrecognised theme name throws a named exception rather than a "view not found".

Available themes:

• bootstrap3 — AdminLTE-friendly
• bootstrap5
• tailwind

Only the markup differs. Sorting, filters, the column picker, resizing and the width-carrying <colgroup> are driven by the component, so every theme behaves identically. The stylesheet and resize script are shared (crewgrid::assets); each theme adds only what its framework needs.

Restyling buttons, inputs and links

Every control the grid renders takes its classes from the theme, and you can override them without publishing a view. App-wide, naming only the keys you want to change:

Or per grid:

The keys are button, input, select, link, badge and action; defaults live in CrewGrid\Grid::DEFAULT_CLASSES. Anything you leave out keeps the theme's default, so there is never a need to restate a whole theme.

Variants. Any control takes a dotted suffix, and an unknown one falls back to the base control rather than rendering unstyled:

So you are not limited to one kind of button. Define as many as you like:

Buttons inside cells. Action buttons in a column are rendered by your format() callback, so hardcoding btn btn-xs bg-purple there ties that grid to Bootstrap 3. actionLink() builds a themed, escaped link instead — and because columns() is a method on your component, $this is available inside the callback:

Shipped variants are primary, info, success and danger, plus the plain action. For markup actionLink() can't produce (a button with an icon, a wire:click), build it yourself and reach for the same classes: '<button class="'.$this->uiClass('action.danger').'" wire:click="...">'.

For anything CSS can reach, you don't need either — the grid's own hooks are stable class names: .crewgrid-table, .crewgrid-bordered, .crewgrid-th-label, .crewgrid-resizer, .crewgrid-popover, .crewgrid-popover-footer, .crewgrid-options.

Publish the views only when the markup has to change (different icons, an extra toolbar control):

Views resolve per file, so delete the ones you didn't mean to own — whatever you keep is frozen at that version and stops receiving updates.

Icons

The themes ship Font Awesome 4 markup, because that is what they were built against. Nothing is hardcoded in the views — every icon comes from a map you can override, a key at a time or wholesale:

Values are markup, not class names, so any icon set works — Font Awesome 6, Bootstrap Icons, Heroicons, Lucide, inline SVG. A key mapped to '' renders nothing rather than a broken glyph, and a key you leave out keeps its default. Per grid, use public array $icons = [...].

Keys: filter, columns, clear, show_all, resize, load_more, loading, sort, sort_asc, sort_desc — see CrewGrid\Grid::DEFAULT_ICONS.

Your own icons. Column headers and action buttons take them too:

Both take markup and render it unescaped — it is yours, not user data. The action link's label is still escaped.

If you use no icon font at all, map every key to '' and the grid renders on text alone.

Tailwind setup

The Tailwind theme uses utility classes, so Tailwind has to be told to scan the package or they will be purged. It needs two paths — the Blade views, and the PHP file the control classes live in:

The second one is easy to miss. Theme markup is in Blade, but the button, input and action.* variant classes are values in Grid::DEFAULT_CLASSES — a PHP file the scanner has no reason to look at otherwise. Leaving it out costs 21 utilities (measured against Tailwind 3): the table renders correctly, but every action.* button loses its background colour, the per-page select and the hidden-column badge lose their padding and shape, and — the one that actually matters — inputs lose focus:ring-1 / focus:border-indigo-500 / focus:outline-none, so keyboard focus becomes invisible.

The alternative, if you would rather not point Tailwind at vendor/ twice, is to define the classes in your own config, where your scanner already looks:

Config files are not scanned either by default, so add './config/crewgrid.php' to content if you take that route — the point is that it is your file, in a path you control, rather than one inside vendor/.

Table padding, striping, hover and row lines ship as plain CSS with the theme rather than as utilities, so a grid still renders legibly if you get any of this wrong — you'll just get an unstyled toolbar rather than an unreadable page. Icons are Font Awesome class names (fa fa-filter), the same as the Bootstrap themes; swap them in a published view if you use a different icon set.

Excel export

Every grid has an Excel button that downloads the current result set — filters, quick search and sort applied, all pages, not just the visible one. Visible columns shape the file (the column picker applies), and rows stream from the database in chunks, so large grids export without loading everything into memory.

The .xlsx is produced by the package's own writer — no spreadsheet library required, just ext-zip. Strings are written as inline strings (a value starting with = arrives as text, never as a formula), PHP ints and floats become numeric cells, and numeric-looking strings stay text so item numbers keep their leading zeros.

What a cell exports:

1. ->exportAs(fn ($value, $row) => ...) if set — always wins.
2. Otherwise the ->format() result, for plain text columns.
3. ->html() and ->view() columns fall back to the raw field value — their rendered output is markup, which has no place in a spreadsheet. Give them an ->exportAs() if the raw value isn't what you want, or ->notExportable() to drop them.

Configuration:

Rename the file per grid:

URL state

Grid state serializes to the query string automatically:

Opening that link restores the exact grid view.

Status

Stable (1.x) — extracted from production use, with its own test suite run across the full support matrix (Laravel 10–13, PHP 8.1–8.5, including a --prefer-lowest floor job) on CI. Feedback and issues welcome.

License

MIT