Sorting, filtering & search

Sorting

Sorting is multi-column. Columns with a declared type sort with that cell type's compare (numbers numerically, dates chronologically); untyped columns use a numeric-aware localeCompare. Empty cells sort last in both directions. Click a header to sort by that column. Shift-click adds another column to the sort without clearing the first.

headerClickBehavior="sort" on DataGridProvider makes a plain header click cycle through ascending, descending, and clear. The default, "select", instead selects the whole column. See Selection & keyboard:

<DataGridProvider headerClickBehavior="sort" {...grid} columns={columns}>

Per-column sortable: false removes a column from the click-to-sort gesture, though you can still sort it programmatically. Read sort state through useDataGridSortState() and drive it through useDataGridActions().setSorts() or .toggleSort().

Filtering

Per-column operators include contains, notContains, equals, notEquals, startsWith, endsWith, empty, and notEmpty, plus gt, gte, lt, lte, and isBetween for numeric and date columns, and isAnyOf for select columns. isBetween renders two typed inputs (from and to) side by side instead of one. isAnyOf renders a checkbox list of the select column's own choices and keeps a row when its value equals any checked one; its value is a string[], and an empty list matches no rows. DataGridFilterMenu is a popover that lists active filters as aligned rows (join cell, column, operator, value, trash, drag handle) with add and reset controls. Per-column filterable: false excludes a column from the menu's column picker. Row order is array order in FilterSpec[]. Drag the grip, or reorder through the keyboard (see below), to change it.

DataGridFilterMenu, along with the search input and columns menu below, comes from the data-grid-toolbar add-on.

pnpm dlx shadcn@latest add @gridcn/data-grid-toolbar

import {
  DataGridToolbar,
  DataGridSearch,
  DataGridFilterMenu,
  DataGridColumnsMenu,
} from "@/components/data-grid-toolbar/data-grid-toolbar";

<DataGridProvider {...grid} columns={columns}>
  <DataGridToolbar>
    <DataGridSearch />
    <DataGridFilterMenu />
    <DataGridColumnsMenu />
  </DataGridToolbar>
  <DataGridRoot>
    <DataGridHeader />
    <DataGridBody />
  </DataGridRoot>
</DataGridProvider>;

Keyboard & accessibility

Plain ArrowUp or ArrowDown on a focused grip always moves the row by exactly one position. The keyboard sensor of @dnd-kit/react also offers its own gesture for that key, but gridcn checks the plain arrow press first, and it wins. Every reorder announces the change through a polite aria-live region (labels.toolbar.filterReorderAnnouncement, for example "Name filter moved to position 2 of 3"). Focus never gets lost. After a reorder, focus stays on the moved row's grip. After deleting a row, focus moves to the next row's grip, or to the "Add filter" button once the list is empty.

Search

DataGridSearch is a quick-search input across visible columns, with match highlighting and next and previous navigation that shows a current/total counter. Navigating to a match moves the active cell there and scrolls it into view, so results are never left off-screen.

It never narrows the row set. Search highlights and navigates matches over the rows already in data; viewIndex is untouched, so everything that walks viewIndex — export with scope: "view", select-all, pinned-row aggregates — sees the same rows with or without a search term. To actually remove rows, use a filter.

DataGridSearch makes itself the "feels native" stand-in for browser find automatically. Pressing Mod+F while focus is anywhere inside the grid or its toolbar focuses this input instead of opening the browser's find bar (preventDefault, so native find never opens). Pressing it again while the input is already focused selects its text, matching how browser find-bars behave when re-triggered.

To opt out and always defer to the browser's native find:

<DataGridSearch captureFindShortcut={false} />

Sort list (toolbar add-on)

Click-to-sort headers work without any add-on, but data-grid-sort-list gives users a toolbar button and popover to add, remove, and reorder sorts without touching the headers. This is useful when columns are hidden or narrow, or when you prefer not to rely on shift-click for multi-column sort:

pnpm dlx shadcn@latest add @gridcn/data-grid-sort-list

import { DataGridSortList } from "@/components/data-grid-sort-list/data-grid-sort-list";

<DataGridProvider {...grid} columns={columns}>
  <DataGridToolbar>
    <DataGridSortList />
  </DataGridToolbar>
  <DataGridRoot>
    <DataGridHeader />
    <DataGridBody />
  </DataGridRoot>
</DataGridProvider>;

Each row has a column select, an ascending/descending select, a remove button, and a drag handle. Precedence is array order in SortSpec[], changed by dragging the grip (@dnd-kit/react) or through the keyboard (see below). It reads and writes the same useDataGridSortState() and useDataGridActions().setSorts() as click-to-sort headers, so the two UIs stay in sync automatically. The button shows a count badge once one or more sorts are applied, matching the badge of DataGridFilterMenu.

Keyboard & accessibility

Plain ArrowUp or ArrowDown on a focused grip always moves the row by exactly one position. The keyboard sensor of @dnd-kit/react also offers its own gesture for that key, but gridcn checks the plain arrow press first, and it wins. Every reorder announces the change through a polite aria-live region (labels.sort.sortReorderAnnouncement, for example "Age sort moved to position 1 of 2"). Focus never gets lost. After a reorder, focus stays on the moved row's grip. After deleting a row, focus moves to the next row's grip, or to the "Add sort" button once the list is empty.

Controlled mode (server-side sort/filter)

By default, sortState, filterState, and searchText are internal, uncontrolled store state. Read them through useDataGridSortState(), useDataGridFilterState(), and useDataGridSearchText(), and write them through useDataGridActions(). The grid sorts, filters, and searches against the data you passed, in-process. Each has a controlled prop pair on DataGridProvider or DataGrid: sortState/onSortChange, filterState/onFilterChange, and searchText/onSearchTextChange, for a "send the spec to the server, render whatever comes back as the view" mode. This follows the same controlled-input convention as a plain <input value onChange>, where the prop, once you pass it, is the source of truth, and onXChange fires on every user-driven change regardless. See the "controlled pair" row of the Events & state three-shapes table for the canonical definition, and Recipes for the full server-side pattern.