Filter State & API

Read what the user filtered, save it, put it in a link, and set it from code. One snapshot object carries all of it.

Saving and restoring filters

This grid opens filtered from code. Change the filters, save them, and reload — yours come back instead.

This grid opens filtered to Engineering, sorted by salary, and neither came from a click. A snapshot passed to [initialState] is how you open a page on a view you chose.

Change the filters, press Save filters, then reload the page — your filters come back instead of the ones from code. Restore filters puts the saved set back without a reload, and Forget clears both the storage and the grid.

Only filters is saved here. getState() hands you sorts, columns and page as well; save the slice you actually want to own.

Putting filters in the URL

Filter the grid and watch the address bar. The link you end up with reproduces the view for whoever you send it to.

(no filter in the address bar yet)

Filter this grid and watch the address bar. The filter state is written into the query string, so the link in your browser now reproduces exactly what you see. Copy it into a new tab and the grid opens filtered.

The URL is updated with replaceState, not a navigation, so the Back button still means "the page before" rather than "the filter before". Reading it back is one line in [initialState], which means the first request already carries the filter.

Showing how many filters are active

A count that updates on every applied change, and one button that clears the lot.

(filterChange) hands you the whole filter state after every applied change. Counting the active ones is a filter over its values — and "active" is worth defining once: an emptied box is not a filter, while blank and not blank are, even though they hold no value.

Clear all writes the state instead of clearing it field by field: setState({ filters: {} }). The filter row empties, the chip disappears and the grid reloads once.

Three calls and one event

Everything on this page is built from four things, and none of them is filter-specific — they carry the whole interactive state, and you keep the slice you care about.

getState() — the current sorts, filters, columns and page, as plain data.
setState(snapshot) — put some of it back. Omitted keys are left alone.
[initialState] — applied before the first request, so your server never sees a throwaway one.
(filterChange) — fires after every applied change, with the new filter state.

A filter state is a plain object keyed by column.key, so JSON.stringify is all the serialising it needs — into storage, into a URL, into a row of your own saved-views table.

{
  department: { op: 'contains', value: 'Engineering' },
  salary:     { op: '>=',       value: 90000 },
}

Restoring costs one request, not two

Pass a snapshot to [initialState] and the filters are applied before the grid fetches anything. Call setState() later and the grid reloads once with the restored filters. Either way the reader sees one load.

Clearing is a whole-snapshot write

There is no clearFilters() and no per-column setter. To clear, write the filter state you want: setState({ filters: {} }) for all of them, or a copy of the object with one key removed for a single column. It is one line either way, and it is the same call you already use to restore.

What a saved filter does not include

Column widths, order and visibility are a separate job with its own option — config.persistColumns saves them on every change with no code. Keep the two apart, or the same data ends up in two places and drifts.

Filter state API

Property	Type	Default	Description
grid.getState()	() => GridStateSnapshot	—	Current sorts, filters, columns and page as serialisable data.
grid.setState(snap)	(snap: Partial<GridStateSnapshot>) => void	—	Restores the keys you pass and leaves the rest alone. A filter change triggers one reload.
[initialState]	GridStateSnapshot	—	Applied before the first `fetchRows()`, so the first request already carries the filter.
(filterChange)	FilterState	—	Fires after every applied filter change, in both `row` and `popup` mode.
(stateChanged)	GridStateSnapshot	—	Fires on any state change — the hook for auto-saving a view.
GridStateSnapshot.filters	FilterState	—	Plain object keyed by `column.key`: `{ op, value }` per column. JSON-serialisable.
config.persistColumns	{ mode, key }	—	Saves column width, order, pin and visibility automatically. Not part of the filter snapshot.