laravel-inertia-datatable

Reusable DataTable for Laravel + Inertia + React, built on shadcn/ui and TanStack Table, with pagination, sorting, filters, global search and column visibility resolved on the server.

Version 0.1: backend and React UI. The Vue version is in progress. Changes in CHANGELOG.md.

What this repo contains

The contract between frontend and backend is in docs/contract.md.

Backend installation

composer require eduardoapatat/laravel-inertia-datatable
php artisan vendor:publish --tag=inertia-datatable-config   # optional

Requires PHP 8.3+ and Laravel 12 or 13. It can also be installed straight from GitHub (vcs repository):

"repositories": [
    { "type": "vcs", "url": "https://github.com/eduardoapatat/laravel-inertia-datatable" }
]

Or from a local folder (path), useful for development:

"repositories": [
    { "type": "path", "url": "../laravel-inertia-datatable", "options": { "symlink": true } }
]

With these repositories: composer require eduardoapatat/laravel-inertia-datatable:@dev.

Creating a table

php artisan make:datatable ProductsTable                 # only the class (guessed model: App\Models\Product)
php artisan make:datatable ProductsTable --react         # + component components/data-tables/products-table.tsx
php artisan make:datatable ProductsTable --page          # + component + page pages/products/index.tsx
php artisan make:datatable ProductsTable --react --install-ui   # also installs the generic UI if missing
php artisan make:datatable OrdersTable --model=Domain/Sales/Order --empty

It proposes the columns from the model casts and the table schema: text (searchable and sortable), numbers, booleans, dates, enums (multiSelect(Enum::class)) and belongsTo relations (category_id → from('category.name')). It skips the primary key, $hidden attributes and sensitive columns (password, remember_token…).

React has two levels: the generic components (components/data-table/, hook and libs) are installed once per project from the registry, and each table has its own component (components/data-tables/<resource>-table.tsx) reusable in any page. The PHP class decides which columns are shown and in which order (also the order of the filters): the columns the component does not declare are rendered with a default cell for their type, and the component only declares the columns it wants to customize (for example, a cell with a badge) or the ones that only exist on the client (actions or selection, at the end unless meta: { position: 'start' }).

The layout (search, filters, Reset, column menu and pagination) is also changed in each table's component, without touching the shared components: DataTableToolbar is made of exported pieces (DataTableSearch, DataTableFilters, DataTableFilter, DataTableResetButton, DataTableViewOptions) that can be placed in any order, and with <DataTable pagination={false}> the DataTablePagination goes wherever you want (for example, on top). --install-ui runs shadcn add with the lockfile's package manager and answers "no" to overwriting existing ui/ files; the registry URL is set in inertia-datatable.registry_url or with the INERTIA_DATATABLE_REGISTRY_URL variable (a URL or a local folder with the compiled JSON, for example to pin the UI to a version). The UI is installed even when the table is not created (unknown model or existing class). When the model does not exist, the command lists the available models.

Installing or updating the UI

php artisan inertia-datatable:ui            # installs the generic UI if missing
php artisan inertia-datatable:ui --update   # updates only the DataTable files (asks for confirmation; --force to skip it)

The update uses the data-table-react-files item, which overwrites components/data-table/*, components/ui/faceted.tsx, the hook and lib/data-table-*.ts, without touching the rest of the project's components/ui/. Local changes to those files are lost.

The stubs can be customized with php artisan vendor:publish --tag=inertia-datatable-stubs.

Frontend installation (React)

In a project with Laravel's React starter kit:

php artisan inertia-datatable:ui            # or make:datatable … --install-ui
php artisan inertia-datatable:ui --update   # brings the new version of the DataTable files

From the registry of the same version as the package, it installs @tanstack/react-table v9, the useServerDataTable hook, the components in resources/js/components/data-table/ and the missing shadcn primitives, answering "no" to overwriting the existing ui/ files (the DataTable only uses variants the starter kit already has). By hand:

pnpm dlx shadcn@latest add https://raw.githubusercontent.com/eduardoapatat/laravel-inertia-datatable/v0.1.0/r/data-table-react.json

For usage in pages, see make:datatable --react above and the skill's React reference (skill/laravel-inertia-datatable/references/react.md).

Claude Code skill

So Claude Code knows how to install the package and create tables in a project:

pnpm dlx shadcn@latest add https://raw.githubusercontent.com/eduardoapatat/laravel-inertia-datatable/v0.1.0/r/data-table-skill.json

It is placed in .claude/skills/laravel-inertia-datatable/.

Development

composer install
composer test           # Pest
composer format         # Pint
composer analyse        # Larastan
composer check          # all of the above (Pint in --test mode)
pnpm install
pnpm run test           # tests of the shared code (Vitest)
pnpm run check          # format and lint (vite-plus)
pnpm run types:check
pnpm run registry:build # compiles registry.json into r/

Tests use in-memory SQLite; for another engine pass Testbench's variables, for example DB_CONNECTION=pgsql DB_HOST=127.0.0.1 DB_PORT=5432 DB_DATABASE=testing DB_USERNAME=postgres DB_PASSWORD=password vendor/bin/pest.

The CI (.github/workflows/) runs:

• tests: Pest with PHP 8.3 to 8.5 and Laravel 12 and 13, MySQL 8.4 and Postgres 17, and the registry (format, tests, types and that r/ is rebuilt).
• starter kit: creates a clean React starter kit, installs the package and the UI of the commit with make:datatable --react --page --install-ui (with npm and with pnpm) and runs the starter kit's composer ci:check. It also runs every week, because the installer uses shadcn@latest. It can be run locally with .github/scripts/starter-kit.sh npm /tmp/app.

Releasing a version

1. Move the ## [Unreleased] entries of CHANGELOG.md to the new version.
2. Change the version in the registry URLs of the README and the skill (…/vX.Y.Z/r/…) and rebuild r/.
3. Commit, annotated tag vX.Y.Z and push the tag. Packagist publishes it by itself; inertia-datatable:ui installs the UI of that tag.

Credits

Part of the frontend code includes third-party MIT-licensed software; see THIRD-PARTY-NOTICES.md.