Pagination and URL state

Diagnosing cursor configuration

Cursor configuration errors include the table class and keep their LogicException type. If no sort is available, set $defaultSort to a declared sortable base-table column. Relationship sorts are unsupported in cursor mode; the error identifies the attribute. For raw/expression orders, inspect query(), withQueryBuilder() and column sortUsing() callbacks and use plain column orderBy calls. Choose full or simple pagination if those restrictions do not fit the query. These diagnostics do not dump SQL or query bindings.

Every table normalizes its own query-string state before applying it to the database. Choose a pagination mode based on the count and navigation behavior the screen needs.

Pagination modes

use Musing\InertiaTable\PaginationType;

protected ?PaginationType $paginationType = PaginationType::Simple;

TopicsTable::make()->paginationType(PaginationType::Cursor);

Mode	Query behavior	Renderer controls
Full	Runs an exact count	First, previous, page window, next, last
Simple	Fetches one extra row, without result count	Previous, next, page number
Cursor	Uses keyset pagination, without page/count query	Previous and next

Configure the default with pagination_type, a table property, or the runtime fluent method.

Cursor requirements

Cursor pagination requires a declared sort on a plain, non-null base-table column. The package adds the qualified primary key as a deterministic tie-breaker. Relationship and expression sorts are rejected because cursor boundaries cannot be reconstructed safely.

All-matching selection remains exact in every mode. A table with bulk actions or a selected export may still run a selectable-count query so confirmation counts and the header checkbox remain correct.

URL namespace

State is isolated below the table name:

?table[topics][search]=laravel
&table[topics][sort]=-created_at
&table[topics][filters][status][enabled]=1
&table[topics][filters][status][clause]=equals
&table[topics][filters][status][value]=published
&table[topics][columns][created_at]=0
&table[topics][columnOrder][]=name
&table[topics][columnWidths][name]=320
&table[topics][page]=2
&table[topics][perPage]=25

The package translates this to Spatie Query Builder parameters internally. Invalid columns, sorts, clauses, values, and page sizes are ignored or replaced with table defaults before query execution.

What state is stored

• global search;
• sort attribute and direction;
• enabled filters, clauses, and normalized values;
• column visibility, order, width, and pinning;
• page or cursor;
• page size;
• selected Saved View.

Selection is client state and is not copied into the URL. It is cleared when the active search or filters change.

Inertia visits

The renderer performs GET visits with preserveState, preserveScroll, and a partial only list containing the table name plus reloadProps. Search and layout updates replace history by default so typing and dragging do not create an unusable Back-button history.

A related counter stays stale

Partial visits refresh the table prop. Declare additional page props when a counter or summary outside the table must refresh with it:

use App\Tables\TopicsTable;

// In the host route/controller response:
'topics' => TopicsTable::make()->reloadProps(['topicCount']),

The host must also return topicCount as an Inertia prop. reloadProps requests that prop; it does not calculate it or change its authorization scope.

Search changes when another control is used

Search is debounced. If you type and immediately sort or navigate, the pending search is included in that visit and pagination resets for the new search. Leading and trailing whitespace is normalized. A newer draft typed while the request is in flight is retained instead of being replaced by the earlier response. Check the request's table namespace and returned search state before adding a second host watcher that triggers its own visits.

Deep links

Share normal search, sort, filter, and column state directly. Treat cursor values as opaque and short-lived; do not construct or persist them outside the table state generated by the package.