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.
| Prop | Purpose | Default |
|---|---|---|
sortState | The sort, controlled by your code | none |
defaultSortState | The sort, seeded once | none |
sortMode | "client" sorts data. "server" only tracks the sort | "client", or "server" with totalRowCount |
sortLocale | The language tag for text compares in a client sort, text range filters, and the filter value lists | the locale prop, then "en-US" |
onSortChange | Fires with the next sort | none |
filterState | The filter tree, controlled by your code | none |
defaultFilterState | The filters, seeded once | none |
filterJoin | The join of the top-level filters, controlled by your code | none |
defaultFilterJoin | The join of the top-level filters, seeded once | "and" |
onFilterJoinChange | Fires with the next join of the top-level filters | none |
filterMode | "client" filters data. "server" only tracks the filters | "client", or "server" with totalRowCount |
onFilterChange | Fires with the next filter tree | none |
searchText | The quick search text, controlled by your code | none |
defaultSearchText | The quick search text, seeded once | none |
onSearchTextChange | Fires with the next text | none |
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. setSortswith 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
sortStateprop 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
setSortscall.
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:
isBetweentakes an inclusive[min, max]pair. An empty string leaves that bound open.isAnyOfandisNoneOftake astring[]. An emptyisAnyOflist matches no row. An emptyisNoneOflist matches every row.emptyandnotEmptytake 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.