Filter builder
A dialog where the user assembles conditions into AND/OR groups, nested as deep as they like. One boolean turns it on:
import { EnterpriseDataGrid } from '@kanunilabs/datagrid-react-enterprise';
<EnterpriseDataGrid
licenseKey={key}
dataSource={rows}
rowKey="id"
columns={columns}
filterBuilder
filterPanel
/>
That adds a Filter builder… button above the grid plus a chip showing the
active filter with a Clear button. Every word of the dialog and that bar comes
from the grid's dictionary, so they follow locale. Pass filterBuilderBar={false}
(filterBuilderBar: false in plain JavaScript) to leave the bar out and open
the builder from your own button, from the filter panel's chevron, or from the
header filter, described below. filterPanel is the companion: a bar under
the footer that spells the effective filter out as a sentence — pass
'always' to keep it visible when nothing is filtered.
Vanilla is the same field on createEnterpriseGrid, and there you can also open
it from code:
const grid = createEnterpriseGrid(el, { /* … */ filterBuilder: true });
grid.openFilterBuilder();
Opening it from code, and from a column
From anywhere in your app, with or without the bar:
controller.openFilterBuilder(); // the dialog, with the filter as it is
controller.openFilterBuilder('amount'); // …starting on that column
Starting on a column shows that column's condition when the filter already has one, and adds an empty condition for it when it has none.
From the keyboard: the dialog takes focus when it opens, Tab stays inside it, Esc closes it, and closing it — any way — gives focus back to the column's header, or to the button it was opened from. In the header filter, Tab reaches (Custom…) and Enter opens it.
Where a builder can be opened, the header filter (headerFilter) shows a first
entry, (Custom…), under its search box. It closes the popup and opens the
builder on that column, the way the custom filter of other grids does.
If your app passes its own onOpenFilterBuilder (to open a dialog of your own),
the filter panel's chevron and the (Custom…) entry call it, with
{ columnId }, and the grid's builder stays available through
controller.openFilterBuilder(). Without it, the Enterprise grid opens its own.
The tree it produces
The dialog writes a serialisable AST — store it, restore it, send it to a server:
type FilterNode = FilterCondition | FilterGroupNode;
interface FilterCondition {
columnId: string;
operator: FilterOperator; // 'contains' | '=' | '>' | 'between' | 'blank' | …
value?: unknown; // array for 'in', [min, max] for 'between'
}
interface FilterGroupNode {
logic: 'and' | 'or';
nodes: FilterNode[]; // every "+ Group" nests one of these
}
controller.setFilter({
logic: 'and',
nodes: [
{ columnId: 'status', operator: '=', value: 'open' },
{
logic: 'or',
nodes: [
{ columnId: 'amount', operator: '>', value: 10_000 },
{ columnId: 'priority', operator: '=', value: 'high' },
],
},
],
});
controller.getFilter() reads it back; controller.setFilter(null) clears it.
Relative dates
A date column offers is in a period next to the fixed comparisons: today, yesterday, tomorrow, this / last / next week, month, quarter and year, year to date, and the last or next N days (today included). The condition stores the period, not the dates:
controller.setColumnFilter('placed', {
columnId: 'placed',
operator: 'period',
value: { period: 'lastDays', days: 7 }, // or { period: 'thisMonth' }
});
So a saved view filtered to "this month" still means this month next month.
The grid turns the period into an ordinary between over two instants each
time it filters, so the worker and a server-side data source receive a plain
range and need no calendar of their own. Periods are local calendar days,
weeks start on Monday, and a filter set yesterday is re-evaluated on the next
filter, sort or data change — the grid does not wake itself at midnight. The
operator works in every edition from code; the dialog is Enterprise, and the
Community filter row takes a period by name ("this month", "the last 30 days")
in a date column's box.
Two filters, not one
This is the part that catches people. The grid holds two filter sources:
| source | where it lives | read with |
|---|---|---|
| the builder | the programmatic slot | controller.getFilter() |
| header funnel + filter row | per-column state | column state |
| both, combined | — | controller.getEffectiveFilter() |
The builder writes only to the first. A condition the user set through the
header funnel does not appear in the dialog and is not removed by its
Clear button. The filterPanel sentence describes the combined result, which is
why it is worth turning on alongside the builder.
The filterChanged event follows the panel, not the builder:
controller.events.on('filterChanged', ({ filter }) => {
// `filter` is the EFFECTIVE filter — builder plus every column filter.
// It is NOT the same value as controller.getFilter().
});
What this does not do
- The
inoperator is missing from the dialog. The AST has 14 operators and the builder offers 13; multi-value membership is produced only by the header funnel's checkbox list. - The column dropdown lists visible, ungrouped columns. Hidden columns, and
grouped ones while
showGroupedColumnsis off, are not offered — write those conditions withcontroller.setFilterinstead. - The dropdown ignores
filterable: false. The editing command column is declared unfilterable and still shows up in the list. - Empty nodes survive. Apply sends
nullonly when the root group is empty; a nested empty group stays in the AST (harmless — the engine reads it as true — but visible in a saved view), and a condition left blank is applied as written. - No validation. Nothing caps condition count or nesting depth, and
betweenwith From greater than To raises no warning — it simply matches nothing. =is unreliable on dates. The date input produces ayyyy-mm-ddstring and equality compares it against the stored cell, so aDateobject or a differently formatted ISO string never matches. The ordering operators (>,>=,<,<=,between) are date-aware and correct.- Lookup columns compare the stored code. The value field is plain text and the engine matches the code, not the label the user sees on screen. Reading is fine — the panel sentence resolves codes to labels — but typing the label does not match.
- Some chrome is untranslated.
+ Condition,+ Group,Apply,Clear all, the AND/OR options and theColumn/Operator/Value/From/Toaria-labels are hardcoded English. Title, operator labels, Cancel, the empty-group text and the value placeholder come from the dictionary. - Community has the hook, not the dialog.
onOpenFilterBuilderexists on the CommunityDataGridand draws a chevron on the filter panel, but it opens nothing on its own — the application supplies the UI. - React and vanilla only. The
prefilter-builderin the Angular packages belongs to PivotGrid and speaks a different AST; the two are not interchangeable. - Test hooks are asymmetric.
data-testidattributes exist on the vanilla dialog only (dg-filter-builder,dg-filter-builder-apply, …). Reach the React dialog through aria-labels and the.kanuni-datagrid-filter-conditionclass.