Laravel Inertia Table Laravel Package

Getting Started

This is a small, early-stage package (Zonvoir-technologies/laravel-inertia-table) that pairs a Laravel-side table builder with a Vue adapter for Inertia apps. It is at v1.0.2, so treat the source and README as the primary reference — the docs were only just fleshed out in this release.

1. Install the Composer package as you would any Laravel library, then install/publish whatever the service provider exposes (config and any Vue components). The v1.0.2 README now includes Composer package info and a basic usage example — read that first, it is the only end-to-end sample currently published.
2. Read the Vue adapter README (overhauled in this release). The PHP side only produces data; the adapter is where columns, cells and navigation actually render. Going PHP-first without reading the adapter docs is the most common way to get stuck.
3. Start with one server-driven table: a controller that returns Inertia props (rows + pagination meta) plus a single Vue page that mounts the table component. Keep sorting/filtering out of the first iteration.

First use case worth building: a paginated index page (e.g. Users/Index) where page changes go through Inertia's router. That path is exactly what v1.0.2 patched, so you are starting on the fixed behaviour.

Because the package is pre-1.x-in-spirit (v1.0.x, two PRs in this release), budget time to read the adapter source when something is undocumented.

Implementation Patterns

Server-driven, Inertia-native. The package is designed around Inertia visits rather than client-side data fetching. Keep the query, pagination and filters in the Laravel controller and pass them as props; let the Vue adapter handle presentation and navigation. This keeps you inside Inertia's model and is where preserveScroll / preserveState become relevant.

Navigation options belong on the table, not the link. Since v1.0.2, table navigation respects preserveScroll and preserveState. Configure them once at the table level rather than sprinkling router.get(..., { preserveScroll: true }) calls around your page. Typical pairing:

• preserveScroll: true — long lists where jumping to the top on page 2 is jarring.
• preserveState: true — when filters/search live in local component state and must survive a page change.

Incremental adoption. Mount the table on one page first, confirm the props shape the adapter expects, then extract a reusable table definition (a PHP class or config array) and reuse it across index pages. That definition is the natural seam for adding columns later.

Wrap it, don't scatter it. Put a thin project-level wrapper component around the adapter's table so that a future breaking change in the package is a one-file edit. Given the release cadence, this is cheap insurance.

Filters and sorting. Drive these through query strings so Inertia's URL state stays the source of truth; the table then only needs to know how to trigger a visit with the new query. This also makes the preserveState behaviour predictable instead of depending on component internals.

Gotchas and Tips

• Pin a minimum version. If you rely on scroll preservation during pagination, require ^1.0.2. v1.0.1 ignored preserveScroll / preserveState on table navigation — the bug is silent (nothing errors, the page just jumps), so it is easy to misattribute to your own Inertia config.
• Scroll bugs usually aren't the package. When preserveScroll appears broken, check for a wrapping element with its own scroll container or a layout that remounts on navigation before filing an issue.
• preserveState can hide stale data. Preserved component state means a filter that was reset server-side may still look set in the UI. Make sure the server props are the authority and re-sync local state from props where it matters.
• Docs are new. The README was only overhauled in this release; older blog posts or snippets you find may target pre-1.0 APIs. Trust the tagged README for the exact version you install.
• Vue adapter version must match. PHP package and Vue adapter move together in this repo. A mismatched adapter version is the likely cause of "props exist but the table renders empty".
• Extension points are thin. There is no evidence of a broad plugin/hook system at this stage. If you need deep customisation, expect to copy the adapter component into your app rather than configure it — do that deliberately, and note it as technical debt so you can diff against upstream later.
• Debugging tip: dump the Inertia props for the page before touching the Vue side. If rows and pagination meta look right, the problem is in the adapter config; if not, keep it in the controller.
• Upgrade path is low risk here. v1.0.2 contains only a navigation fix and documentation changes — no deprecations or API breaks. Safe to take on any v1.0.x install.