Pagination and URL state

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.

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.