Filtering
Give a column a filter and the grid renders the right control for its type. Choose where the controls live, narrow the operators on offer, and see exactly what reaches your API.
Row filters
A filter control sits inline under each header — every filter visible and reachable without a click.
Popup filters
A funnel icon in each header opens the filter on demand, keeping the header row compact.
Empty and non-empty cells
Some people here have no email on file and some no start date. Open the funnel on Email and pick Blank to find them — the value box goes away, because there is nothing to type.
The value box disappears
Pick Blank or Not blank from a column's funnel and the value box is replaced by a chip naming the operator. That is the point: neither takes an operand, so there is nothing to type and nothing to leave half-finished. Clear it the way you clear any filter.
Both operators sit at the end of the menu on every text, number and
date column. No column config turns them on.
Narrowing the operator list
First Name accepts one operator and has no funnel at all. Salary accepts two. Email is left at the defaults — open its funnel to see the full menu the other two gave up.
One operator means no funnel
First Name above offers only contains, so its funnel is gone
entirely — with a single operator there is nothing to open. Salary keeps its
funnel, because two operators is still a choice. Email is untouched, so the full
menu and the narrowed ones sit in one grid to compare.
The array you pass replaces the default list rather than adding to it — and that includes the presence operators. Narrow a column and Blank / Not blank go with the rest, unless you list them yourself.
Numbers and dates
A numeric input with comparison operators, and the grid's date picker with before/after. Try salary ≥ 90000, then start date after 2020-03-31, and sort on top of both.
Ranges are two conditions
A column filter carries one condition, so a number column gives you a floor or a ceiling
and a date column gives you before or after. "Between 60k and 90k" and "started during
Q1" are two conditions on one column: add multi: true to the column and it holds
both, joined by AND or OR. See Filter Conditions. Two bounds you own yourself are the other route: a pair of date inputs above the
grid becomes one request. See External Filters.
Numbers reach your source as numbers and dates as YYYY-MM-DD strings, so both compare
correctly in SQL with no parsing on your side.
From the filter box to your SQL
The panel under this grid is the real request it just made. Filter or sort, and watch the payload and the query change with it.
What the grid sent
{
"offset": 0,
"limit": 20,
"sorts": [],
"filters": {}
}What your server runs
SELECT * FROM employees
ORDER BY id
LIMIT 20 OFFSET 0Reading the panel
Sort a column and the sorts array grows. Type in a filter and a key appears under
filters. Now clear it and watch what happens: the key stays, with the
value null. A column you never touched is absent from the map; a column you cleared is
present and empty. So read the values, not the keys — Object.keys(filters).length
counts cleared columns too, and skipping null entries is what your server must do
before it builds a WHERE clause.
The SQL underneath is one honest translation of that payload, and the server.js tab is
the code that produces it. Two things there matter more than the shape: column keys pass through a
whitelist before they touch the query, and every value is bound rather than interpolated.
totalCount is the size of the filtered set, not of the table. The grid sizes its scroll
range from it, so a count that ignores the WHERE clause shows a scrollbar for rows that
will never arrive.
Filter UIs: row vs popup
There are two places filters can live, controlled by config.filterMode:
-
'row'— a persistent input row appears directly below the column headers. Each column with afilterconfig gets its own input. Best when filtering is a primary workflow, not an occasional action. -
'popup'— a filter icon appears in each filterable header. Clicking opens a floating popup with the full filter UI including operator selection. The icon turns highlighted when a filter is active on that column. Less visual noise when filters are used occasionally. Toggle between modes using the buttons above the grid.
Filter types
Each column's filter.type controls both the UI and the operator set sent to your API:
'text'— string operators: contains, equals, startsWith, endsWith, notContains. Debounces 300ms by default.'number'— numeric operators: =, ≠, >, ≥, <, ≤. They compare numbers. A cell that holds text such as"1,234"or"12 kg"is not read as a number, because a comma can be a thousands separator or a decimal mark depending on the language, so it never passes =, > or < (it does pass ≠). If your API sends numbers as text, convert them on the column:valueGetter: r => Number(r.amount.replace(/,/g, '')).'date'— date operators: equals, before, after. Opens the grid's own date picker.'select'— single-value dropdown. Pass anoptionsarray of{ label, value }pairs.'boolean'— a Yes / No list for true / false data (equals). A column whose data is boolean gets it without asking.
Blank / Not blank
Every text, number, date and boolean filter also offers two value-less operators —
'blank' (the cell is empty: null, undefined,
or an empty string) and 'notBlank' (its opposite). Pick either from
the operator menu and the value box disappears — there is nothing to type. A whitespace-only cell
counts as non-blank, and 0 / false are real values (never blank), so the
rule stays predictable across every column type. On the server, translate them to a
NULL/empty test (see the employee-api.service.ts tab). Free in Community.
Renaming the operators
Operator labels are strings you own. config.filterLabels.operators takes a partial map
from operator to label, so you can translate them or use your own wording — "Has a value" instead
of "Not blank", say. Unlisted operators keep their defaults, and renaming changes the label only:
the operator sent to your API is unchanged.
config = {
filterLabels: {
operators: { contains: 'Includes', notBlank: 'Has a value' },
placeholder: 'All',
},
};
The same object sets the Apply and Clear labels and the dropdown placeholder. For the text a screen
reader announces on a filter input, use config.messages.filterFor — it takes a
{col} placeholder that is replaced with the column name.
How filters reach your API
When the user changes a filter, the grid resets and calls fetchRows() with the
updated params.filters: a FilterState object keyed by column.key.
Each value is { op: FilterOperator, value: any }. Serialize it and pass it to
your query. A column you never filtered is absent from the map; a column whose filter you
cleared is present with the value null. Skip the null entries before you
build a query — see the last example, where you can watch the difference happen.
The (filterChange) output fires the full FilterState after every change.
Use it for URL sync or analytics — the grid already handles the refetch.
Filter types
| Property | Type | Default | Description |
|---|---|---|---|
| filter.type: 'text' | operators | 'contains' | contains · equals · startsWith · endsWith · notContains · blank · notBlank. |
| filter.type: 'number' | operators | '=' | = · != · > · >= · < · <= · blank · notBlank — restrict via filter.operators. |
| filter.type: 'date' | operators | 'equals' | before · after · equals · blank · notBlank, with the grid's date picker. |
| filter.type: 'boolean' | operators | 'equals' | Yes / No (equals true / false) · blank · notBlank. Picked automatically for boolean data. |
| op: 'blank' | 'notBlank' | presence | — | Value-less: match empty (null/undefined/"") vs non-empty cells. On any text/number/date/boolean filter. Free. |
| filter.operators | FilterOperator[] | the type default | Replaces the operator menu for one column. A single-entry list hides the funnel; the presence operators are dropped unless you list them. |
| filter.type: 'select' | single value | — | Dropdown of static options — one active value at a time. |
| config.filterMode | 'row' | 'popup' | unset — no filter UI | Inline filter row under the header, or popup filters behind a header icon. |
| config.filterLabels.operators | Partial<Record<FilterOperator, string>> | — | Rename or translate operator labels. Unlisted operators keep their defaults; the operator sent to your API is unchanged. |
| params.filters | FilterState | {} | What your data source receives — { [columnKey]: { op, value } }. A never-filtered column is absent; a cleared one is present as null. Skip nulls before building a query. |