Documentation

Filter builder

Try it live:

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();

See it working →

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:

sourcewhere it livesread with
the builderthe programmatic slotcontroller.getFilter()
header funnel + filter rowper-column statecolumn 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 in operator 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 showGroupedColumns is off, are not offered — write those conditions with controller.setFilter instead.
  • The dropdown ignores filterable: false. The editing command column is declared unfilterable and still shows up in the list.
  • Empty nodes survive. Apply sends null only 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 between with From greater than To raises no warning — it simply matches nothing.
  • = is unreliable on dates. The date input produces a yyyy-mm-dd string and equality compares it against the stored cell, so a Date object 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 the Column/Operator/Value/From/To aria-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. onOpenFilterBuilder exists on the Community DataGrid and 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-builder in the Angular packages belongs to PivotGrid and speaks a different AST; the two are not interchangeable.
  • Test hooks are asymmetric. data-testid attributes 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-condition class.