Query String

The query string module synchronizes listing state (page, sort, filters, page size) with the browser URL. This allows sharing links with pre-applied filters and restoring state on page reload.

How It Works

ListingContext uses the query string module internally. When filter, sort, or pagination state changes, the URL is updated automatically. On mount, initial state is read from the URL.

URL Parameters

Parameter	Maps To	Example
`page`	Current page	`?page=3`
`perPage`	Page size	`?perPage=50`
`sort`	Sort column	`?sort=name`
`order`	Sort direction	`?order=asc`
`filter[field]`	Filter values	`?filter[status]=active`

Example URL


/invoices?page=2&perPage=25&sort=createdAt&order=desc&filter[status]=paid

Shareable Links

Because all state is in the URL, users can:

Bookmark filtered views
Share links with colleagues
Use browser back/forward to navigate listing state

KVS Integration

When NEXT_PUBLIC_KVS_DATA_STORE_TOGGLE=1, user preferences (page size, column visibility) are additionally persisted to the Key-Value Store via useKVS, surviving across sessions.