List Filter API

Enterprise

Introduction

A List Filter is applied by the reader ticking boxes in the popup — but your app often needs to drive it from code: seed a default selection, sync it to a toolbar, read what’s currently selected, or clear it on a button. setFilterApi() is that programmatic handle.

Under the hood a List Filter is just an in condition, so you can reach for the raw grid.filter API. What setFilterApi() adds is a set-filter-shaped surface that speaks in values, not conditions: it knows the column’s distinct value list (honouring the column’s values / comparator / valueFormatter, so it matches the popup exactly), and it lets you toggle values individually without hand-rolling the membership maths.

import { setFilter, setFilterApi } from '@zengrid/enterprise';

const columns = [
  { field: 'name', header: 'Name' },
  setFilter({ field: 'region', header: 'Region' }),
];
const grid = new Zengrid(el, { columns });

const region = setFilterApi(grid, columns, 1); // 1 = Region's column index

region.getValues();                       // every distinct region, in popup order
region.setModel({ values: ['APAC'] });    // apply — keep only APAC
region.getModel();                        // → { values: ['APAC'] }
region.selectAll();                       // clear the filter (all rows)

setFilterApi(grid, columns, column) is a licensed enterprise call. column is the data-column index — the column’s position in the columns array — and the value-list options are read from that setFilter() column, so getValues() returns exactly what the popup shows.

The model

The List Filter’s state is expressed as a plain model — the list of checked values, or null for “no filter”:

type SetFilterApiModel = { values: unknown[] } | null;

getModel() / setModel() read and write it. The mapping mirrors the popup:

• null → no filter; every value passes. setModel(null) clears the column.
• { values: [...] } → an in condition of exactly those values. Passing every value is the same as no filter, so setModel() clears it — just like ticking every box.
• { values: [] } → matches no rows.

Because reads go through the grid’s live state, the API and popup stay in lock-step: set the model here and the next popup open shows it; tick a box in the popup and getModel() sees it.

Methods

Method	What it does
getValues()	The distinct values the filter offers, in display order (after the column’s values / comparator). Re-derived from the current data, so it follows setData.
getModel()	The current selection as { values }, or null when no filter is active.
setModel(model)	Apply a selection ({ values }) or clear it (null). Selecting every value clears the filter.
selectAll()	Check every value — clears the column filter.
deselectAll()	Uncheck every value — no rows pass until something is selected.
selectValue(v)	Add one value to the selection.
deselectValue(v)	Remove one value from the selection.
isValueSelected(v)	Whether v currently passes (true when no filter is active).

Try it live

The Region column has a List Filter, and the buttons below drive it purely through setFilterApi() — no popup. The readout under the buttons shows what each read method returns; the grid updates as each write method fires. (Open the funnel afterwards to confirm the popup reflects the same selection.)

Read & set the modelToggle individual valuesMirrors the column’s list

CodeDemoSplit

ResetRun ⌘⏎

getValues() lists every region; setModel({ values }) applies a selection; getModel() reads it back ({ values } or null); selectAll() clears the filter. Watch the readout and the grid.

When to use which API

• Reach for setFilterApi() when you think in terms of values — reading the offered list, toggling a value, or syncing the selection to your own UI. It keeps you aligned with the column’s values / comparator / valueFormatter.
• Reach for the raw grid.filter API when you already have the exact in array and just want to apply it, or when you’re driving several different filter types uniformly.

Both write the same in condition, so they interoperate freely — set with one, read with the other.

Next

• List Filter — the checkbox filter this API drives, and how a selection maps to an in condition.
• Data Updates — keep the selection in step as the grid’s data changes (newRowsAction).
• Filter API — the general grid.filter surface for every filter type.