gridcn2.0.0
Events and state

Sort and filter events

Read or control the sort, the filters, and the quick search text with three controlled props.

Sort, filters, and quick search text each have a controlled prop. The callback reports the next value. The value prop makes your state the source of truth.

PropPurposeDefault
sortStateThe sort, controlled by your codenone
defaultSortStateThe sort, seeded oncenone
sortMode"client" sorts data. "server" only tracks the sort"client", or "server" with totalRowCount
sortLocaleThe language tag for text compares in a client sort, text range filters, and the filter value liststhe locale prop, then "en-US"
onSortChangeFires with the next sortnone
filterStateThe filter tree, controlled by your codenone
defaultFilterStateThe filters, seeded oncenone
filterJoinThe join of the top-level filters, controlled by your codenone
defaultFilterJoinThe join of the top-level filters, seeded once"and"
onFilterJoinChangeFires with the next join of the top-level filtersnone
filterMode"client" filters data. "server" only tracks the filters"client", or "server" with totalRowCount
onFilterChangeFires with the next filter treenone
searchTextThe quick search text, controlled by your codenone
defaultSearchTextThe quick search text, seeded oncenone
onSearchTextChangeFires with the next textnone

With the value prop, your code answers first. The grid writes nothing, and the callback receives the next value. When you pass the new value, the view changes. A controlled grid that ignores the callback stays as it is. Without the value prop, the grid writes the change, then fires the callback.

onSortChange

The callback receives SortSpec[], with the primary sort first. A SortSpec holds columnId and direction, which is "asc" or "desc". It fires for a header click, toggleSort, and setSorts, with or without a sortState prop. This sample controls the sort:

import { useState } from "react";
import {
  DataGrid,
  defineColumns,
  type SortSpec,
} from "@/components/data-grid/data-grid";

type Row = { id: string; name: string };

const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

function Grid({ rows }: { rows: Row[] }) {
  const [sorts, setSorts] = useState<SortSpec[]>([]);
  return (
    <DataGrid
      defaultData={rows}
      columns={columns}
      sortState={sorts}
      onSortChange={setSorts}
    />
  );
}

With sortMode="server", the grid tracks the spec and never reorders data. When the callback fires, fetch the rows in the new order, for example with useDataGridServerRows. See Compare data modes.

Timing and errors

The callback runs synchronously. Without a sortState prop, the grid applies the sort first, and the store holds the new sort inside the callback. With a controlled sortState, the grid writes nothing, the store keeps the old sort inside the callback, and the callback receives the next sort. These rules apply:

  • The sort list, the context menu sort items, URL state, and saved views call setSorts, so the callback fires for them too.
  • setSorts with the current spec does nothing. The callback does not fire. A stale view is the exception: the call rebuilds it and fires the callback.
  • A change of the sortState prop never fires the callback.
  • If the callback throws, the sort stays applied, and the other callbacks of the change still run. Then the grid rethrows the error to the caller, for example the header click handler or your setSorts call.

All callbacks follow one timing rule. See Callback timing and errors.

onFilterChange

The callback receives the whole filter tree as FilterNode[]. A node is a filter row (FilterSpec) or a group (FilterGroup). The top level combines with filterJoin, "and" by default. A group holds join ("and" or "or"), its own filters, and an optional not (true keeps the rows the children do not match). A group nests one more group at most. An empty group matches every row. If you leave out a filterId, the store assigns one.

A FilterSpec holds columnId, operator, and value. The value is a string for most operators. Numbers and dates are text, such as "30" and "2025-01-31". These operators differ:

  • isBetween takes an inclusive [min, max] pair. An empty string leaves that bound open.
  • isAnyOf and isNoneOf take a string[]. An empty isAnyOf list matches no row. An empty isNoneOf list matches every row.
  • empty and notEmpty take no value.

The callback fires for the filter menu, header filters, and setFilters, with or without a filterState prop. setFilters with the current tree does nothing. With filterMode="server", the grid tracks the filters and never filters data. Fetch the matching rows, for example with useDataGridServerRows.

The callback runs after the grid writes the filters. If it throws, the filters stay applied, and the reset to page 1 of a paged grid still fires onPageChange. Then the grid rethrows the error. See Callback timing and errors.

onSearchTextChange

The callback receives the new text. If the text equals the current text, it does not fire. Quick search highlights matches and moves between them. It never filters the rows.

The callback runs after the grid writes the text. If it throws, the text stays, and the grid rethrows the error. See Callback timing and errors.

The toolbar search waits for typing to pause before it commits. Quick search describes the wait and the inputDebounceMs prop.

On this page