Filtering
Hide rows that fail per-column conditions, combine conditions with and/or groups, and set filters from the filter menu or from code.
A filter hides the rows that fail a condition on one column. filterState holds the filters as a list. The top level combines its entries with "and" or "or", as filterJoin says. A group inside the list combines its own entries with "and" or "or". Users build the list in the DataGridFilterMenu popover, and Clear all empties it. Code sets it with actions.setFilters(), and setFilters([]) clears it.
Click a header to sort (click again to reverse, a third click clears it); shift-click another header to add it as a secondary sort. Use Filter in the toolbar for per-column filters; the preset shows a group of two Role rows. Switch the "Or" between them to "And" to change the whole group.
DataGridFilterMenu comes with the toolbar add-on. Put it inside <DataGridToolbar>. Filtering from code needs no add-on.
Filter from code
A FilterSpec is one condition: columnId, operator, and value. A FilterGroup is { join, filters }. Pass both kinds to actions.setFilters(), or seed the list once with defaultFilterState:
"use client";
import { DataGridBody, DataGridHeader, DataGridProvider, DataGridRoot } from "@/components/data-grid/data-grid";
import { defineColumns, useDataGridActions, type FilterNode } from "@/components/data-grid/data-grid";
type Order = { id: string; country: string; name: string };
const columns = defineColumns<Order>()([
{ id: "country", header: "Country", accessorKey: "country" },
{ id: "name", header: "Name", accessorKey: "name" },
]);
const filters: FilterNode[] = [
{ columnId: "country", operator: "equals", value: "NL" },
{
join: "or",
filters: [
{ columnId: "name", operator: "contains", value: "A" },
{ columnId: "name", operator: "contains", value: "B" },
],
},
];
function ApplyButton() {
const actions = useDataGridActions();
return <button onClick={() => actions.setFilters(filters)}>Apply</button>;
}
export function OrdersGrid({ rows }: { rows: Order[] }) {
return (
<DataGridProvider defaultData={rows} columns={columns}>
<ApplyButton />
<DataGridRoot className="h-96">
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}After the click, a row stays if its country is NL and its name contains A or B. A join: "and" group needs every child to match, and "or" needs one. Any other value acts as "and", and an empty group matches every row. not: true keeps the rows the children fail, empty cells included.
A group can contain one level of nested groups. setFilters drops a group nested deeper, with its rows.
Operators
By default, every column offers the text operators: contains, notContains, equals, notEquals, startsWith, endsWith, empty, and notEmpty. number and date columns add gt, gte, lt, lte, and isBetween. text, number, date, select, and untyped columns add isAnyOf and isNoneOf. The longText, url, and checkbox columns offer the text operators only.
| Operator | value | Matches a row when |
|---|---|---|
| Text operators | string | The cell text compares to the value. |
gt, gte, lt, lte | string | The cell is not blank and compares to the value. |
isBetween | [from, to] | The cell is not blank and lies between both bounds, inclusive. An empty bound is open. |
isAnyOf | string[] | The cell text equals one entry. An empty list matches no row. |
isNoneOf | string[] | The cell text equals no entry. An empty list matches every row. |
empty, notEmpty | none | The cell text is empty, or is not. |
Case does not matter, unless the column sets filter.matchCase. Every value is text, even for number and date columns, such as "5". A comparison reads both sides as numbers when both parse. Otherwise it compares them as text.
The filter object of a column changes this behavior for that column:
filter.operatorsreplaces the list of operators the filter menu offers.filter.match(value, filter)replaces the built-in test. It receives the raw cell value and returns whether the row passes. A thrown error fails the row.- With
filter.match, the set operatorsisAnyOfandisNoneOfstill use the built-in set match on the cell text, and the header filter button stays. Yourmatchreceives the set operators only whenfilter.operatorslists them. filter.matchCase: truemakes the text and set operators and the header filter list respect case.filterable: falsekeeps the column out of the filter menu and the header filter.filter.compare(text, bound)orders the cells of a column forgt,gte,lt,lte, andisBetween. Use it for ranks or versions. A result ofNaNor a thrown error falls back to the default order. A column withfilter.matchignoresfilter.comparefor built-in operators.
A cell type takes the same filter object, with a fourth member, valueInput, for the value widget of the filter row. Each member of the column wins over the same member of the cell type.
Custom operators
A column can list its own operators next to the built-in ones. List an object with an id and a label in filter.operators. The filter menu shows the label, and the filter stores the id. A FilterOperator is a built-in operator or any string.
This column registers one operator:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Order = { id: string; city: string };
const inRegion = {
id: "inRegion", label: "is in region", input: "single",
} as const;
const columns = defineColumns<Order>()([
{
id: "city", header: "City", accessorKey: "city",
filter: { operators: ["contains", inRegion] },
},
]);
export function Orders({ orders }: { orders: Order[] }) {
return <DataGrid data={orders} columns={columns} />;
}| Field | Meaning |
|---|---|
id | Stored in filterState, in the URL, and in the spec your server receives. It must not equal a built-in operator. |
label | The text of the operator select. |
input | The value shape: "single" (default), "range" for a from and to pair, "list" for a list of values, or "none" for no value. |
match(text, filter) | Decides on the client whether a row passes. text is the cell text that the built-in operators compare. A thrown error fails the row. |
With filterMode="server", the grid never calls match, so leave it out. In client mode, a custom operator without match does not narrow rows, and the grid warns once in development. useDataGridUrlState writes a custom id to the URL and reads it back.
Custom operators on the server maps the id to a query.
Join the top level
filterJoin sets how the top-level entries combine. "and" (default) keeps a row that passes every entry. "or" keeps a row that passes any entry. An empty list filters nothing.
onFilterJoinChange fires with the next join (props). actions.setFilterJoin(join) sets it from code. A join change resets a paged grid to page 1. With filterMode="server", the spec holds filterJoin: "or" only for "or".
A header filter leaves the join as it is. Under "or", its value list shows every value.
Filter menu
The popover lists the filter tree. The first entry of a list reads "Where". The second entry shows a select with "And" and "Or". That select sets the join of the whole list. Later entries show the same word as text. Each group is a list, and so is the top level.
Each row holds a column, an operator, a value, a remove button, and a drag handle. The title row has "Add filter", "Add group", and "Clear all". Each group has a "Not" toggle and buttons to add a filter, add a group, and remove the group.
A new group takes the opposite join of its parent, so a group in an "and" list starts as "Or". isBetween shows two inputs, and isAnyOf and isNoneOf show a checkbox list.
The menu offers the visible columns. A filter on a hidden column keeps applying and shows its column. Pass allColumns to offer hidden columns for new filters.
Filter menu keyboard & accessibility
| Key | Action |
|---|---|
| Tab | Moves through a row: join (from the second entry of a group), column, operator, value, remove, drag handle. |
| ArrowUp / ArrowDown on the drag handle | Moves the row or group one place among its siblings. |
| Backspace / Delete on the drag handle | Removes the row or group. |
| Escape during a drag | Cancels the drag and keeps the popover open. |
While a pointer drags, a line shows where the row lands. A reorder announces the new place through labels.toolbar.filterReorderAnnouncement, and focus stays on the moved handle. After a removal, focus moves to the handle of a sibling. When the row was the last of its group, the group goes too, and focus moves to a sibling of the group. If no sibling remains at any level, focus moves to "Add filter".
Controlled and initial filters
filterState makes the prop the source of truth, and onFilterChange(next) fires on every change. A controlled grid changes its filters only after the prop changes. defaultFilterState seeds the list once.
Server mode
If your server filters the rows, set filterMode="server". The grid tracks filterState, shows the filter indicators, and calls onFilterChange. It never filters data. A grid with totalRowCount defaults to "server". Set filterMode="client" to filter its data in the browser.
The request is the FilterNode[] that onFilterChange receives, and the answer is the rows that match. useDataGridServerRows sets filterMode for you and passes each fetch the list as request.spec.filters. A filter row of a column with filter.matchCase carries matchCase: true, so your server compares with letter case. See Query server rows.
On a column with choices, the isAnyOf input lists the choices. On other columns, the header filter and the isAnyOf input list the set values of the loaded rows. Pass fetchFilterValues to read them from your server. See Header filter.
Related
- Header filter: the set values in each column header
- Toolbar: the filter menu, search, and columns menu
- Quick search: highlights matches and never hides rows
- ColumnDef: every
filtermember - Sort and filter events:
onFilterChangeand its siblings