URL state options
Look up the options of DataGridUrlState, useDataGridUrlState, and useDataGridUrlPagination, plus the URL keys and their limits.
DataGridUrlState syncs the sort, filter, search, and column layout of the grid with the URL through nuqs. useDataGridUrlPagination syncs the page and the page size. Both need a nuqs adapter above them in the tree.
| Symbol | Purpose | Guide |
|---|---|---|
DataGridUrlState | Component that syncs the view state | URL state |
useDataGridUrlState | Hook behind the component | URL state |
useDataGridUrlPagination | Hook for page and pageSize | URL state |
DataGridUrlState
This sample mounts the component once:
import { NuqsAdapter } from "nuqs/adapters/react";
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
type ColumnDef,
} from "@/components/data-grid/data-grid";
import {
DataGridUrlState,
} from "@/components/data-grid-url-state/data-grid-url-state";
type Person = { id: string; name: string };
const people: Person[] = [{ id: "1", name: "Ada" }];
const columns: ColumnDef<Person>[] = [
{ id: "name", accessorKey: "name", header: "Name" },
];
export function PeopleGrid() {
return (
<NuqsAdapter>
<DataGridProvider defaultData={people} columns={columns}>
<DataGridUrlState
prefix="people"
layout={["order", "hidden", "widths"]}
/>
<DataGridRoot>
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
</NuqsAdapter>
);
}The component renders nothing. Its props, DataGridUrlStateProps, are the options of useDataGridUrlState. Mount it inside DataGridProvider.
useDataGridUrlState
Prop
Type
prefix
The prefix and an underscore start every key of the grid. prefix="people" gives people_sort, people_filter, people_q, people_join, and people_cols. The pagination hook uses the same rule for page and pageSize.
spec
The option picks which parts of the view spec go into the URL. The default is ["sort", "group"]. List "filter" and "search" to share filters and search text. They then reach the browser history, server logs, and the Referer header of the next request. See What leaves the page. spec={[]} turns spec sync off.
| Part | Keys |
|---|---|
sort | sort |
group | group, the groupBy column ids, at most 4. An unknown column, a groupable: false column, and a repeated column drop out. The open groups stay out. |
filter | filter, and join, which the add-on reads once and removes |
search | q |
A part that is not listed is neither read on mount, written on change, nor reset by applyFromUrl().
layout
Each part is a UrlLayoutPart. The default is ["order", "hidden"]. layout={[]} turns layout sync off. A part is in the URL only while it differs from the layout the grid started with.
| Part | Key | Format |
|---|---|---|
order | cols | Column ids, comma-separated |
widths | widths | id:px pairs in whole pixels |
pins | pins | id:s or id:e pairs. - means no pinned column |
Result
Prop
Type
The URL applies to the store on mount and on back and forward navigation. With enableNavigationSync set to false, only the mount applies. After that, the store drives the URL. When the URL changes outside the grid in another way, call applyFromUrl. A key that the URL lacks then clears its sort, filter, or search.
useDataGridUrlPagination
Prop
Type
Prop
Type
The result spreads into DataGridProvider, useDataGridServerPager, or useDataGridServerRows. The URL omits page at 1 and pageSize at defaultPageSize. A change of pageSize resets page to 1.
Limits
A hand-edited URL cannot grow the view state without bound. Every write uses history: "replace".
filter: 64 rows, 16 groups, 256 segments.filterlist values: A column withchoicesallows the larger of its choice count and 64. Other columns allow 1,000. A longerisAnyOflist keeps its first entries. A longerisNoneOflist drops the segment.filtervalue length: A value, a choice, or a range bound over 1,000 characters drops the segment.q: The grid cuts the search text to 500 characters.sort: 64 sorts, 256 segments, one direction for each column.group: 4 segments, one for each column.cols,hide,widths,pins: 1,024 entries. The grid ignores a key over 16,384 characters.pageSize: a value outsidepageSizeOptionsreads asdefaultPageSize.page: An integer from 1 to 1,000,000. Anything else reads as 1.
A sort row for a missing, hidden, or unsortable column drops from the URL state. A group column that is missing, hidden, or groupable: false does the same. A filter row for a missing, hidden, or unfilterable column does the same. Ids that match no column drop from the layout.
Server mode
When data holds part of the result, as with server pages or scroll mode, set sortMode="server" and filterMode="server". The store then holds the restored spec and your fetch applies it. useDataGridServerRows sets both modes, and a grid with totalRowCount gets them by default. Without both modes, the grid sorts and filters only the loaded rows. See Data mode support.
In client filter mode, a column with choices keeps a list value that matches a choice or a loaded data value, without regard to case. In server filter mode every value stays, so check the values on the server. The Limits bound also applies: a longer isAnyOf list keeps its first entries, and a longer isNoneOf list drops the segment.