gridcn2.0.0
Add-on optionsSort, filter, and search

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.

SymbolPurposeGuide
DataGridUrlStateComponent that syncs the view stateURL state
useDataGridUrlStateHook behind the componentURL state
useDataGridUrlPaginationHook for page and pageSizeURL 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.

PartKeys
sortsort
groupgroup, 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.
filterfilter, and join, which the add-on reads once and removes

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.

PartKeyFormat
ordercolsColumn ids, comma-separated
hiddenhideColumn ids, comma-separated. - means no hidden column
widthswidthsid:px pairs in whole pixels
pinspinsid: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.
  • filter list values: A column with choices allows the larger of its choice count and 64. Other columns allow 1,000. A longer isAnyOf list keeps its first entries. A longer isNoneOf list drops the segment.
  • filter value 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 outside pageSizeOptions reads as defaultPageSize.
  • 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.

On this page