Grid State
Persist the grid between sessions. Column widths, order, and visibility save automatically on every change. Sorts and filters can be saved as named views and restored on page load or with a button click.
[initialState] — server sees the right params immediately
This grid opens sorted by salary, highest first, and filtered to Engineering — from a snapshot handed to the input. The very first request already carries both; there is no unfiltered page for the reader to watch get replaced.
[initialState] is applied before the first
fetchRows(), not after it. The request that leaves the browser already carries the
salary sort and the Engineering filter, so the reader never sees an unfiltered page appear and
then get replaced — and your endpoint never serves one.
readonly openingView: GridStateSnapshot = {
sorts: [{ key: 'salary', dir: 'desc' }],
filters: { department: { op: 'equals', value: 'Engineering' } },
};
It is applied once. Changing the object later does not re-apply it — for that,
call setState(), which is the next example. The snapshot itself can come from
anywhere: a literal like this one, localStorage, a route parameter, or a saved view
fetched from your API.
setState() triggers a refetch
Sort or filter this grid, press Save view, change your mind, then press Restore. Restoring calls setState() with the saved sorts and filters, which resets the grid and fetches again with those params.
getState() hands you a plain, serialisable object; setState() takes one
back. Sort or filter this grid, press Save view, change it again, then press
Restore view.
What restoring actually does
A setState() carrying sorts, filters or
quickFilter resets the grid and issues a new fetch with those
params — the same round trip a reader's own click would have caused. A snapshot carrying only
columns does not: widths and order are applied in place, with no request.
getState() returns columns as well as sorts and filters. This example
stores only the three slices it owns:
const { sorts, filters, page } = grid.getState();
localStorage.setItem(VIEW_KEY, JSON.stringify({ sorts, filters, page }));
Clear saved is the same call with empty slices —
setState({ sorts: [], filters: {} }) — which is how you get back to the
unsorted, unfiltered view without reloading the page.
Auto-save pattern
No buttons at all. Every sort and filter is written by (stateChanged) as it happens, and every resize or reorder by persistColumns — two features, two storage slots. Reload the page and this grid comes back exactly as you left it.
demo-grid-state-auto:—No Save button, because nothing waits to be saved. Two features are running here at once, and neither needs a line of imperative code at the moment of the change:
(stateChanged)fires on every sort and filter. The handler writes the three slices it owns to its own key — the readout under the grid is that write, happening.persistColumnswrites every resize, reorder, pin and hide to a different key, with no handler at all, and restores it before the first render.
Sort a column, drag one narrower, then reload the page: the sort comes back from
[initialState] reading the first key, and the width comes back from
persistColumns reading the second. Forget empties both.
Debounce the handler if you are writing to an API rather than to localStorage —
a drag-resize alone can emit several times.
Two tools, two responsibilities
State splits cleanly in two, and the split is the thing worth learning: one half saves itself, the other half is yours to decide about.
| Feature | Saves | How |
|---|---|---|
persistColumns |
Column widths, order, pin, visibility | Automatic on every change — zero code |
getState() / setState() |
Sorts, filters, quick filter, page | Manual (a button) or automatic via (stateChanged) |
Each owns a separate storage key. The three examples above use three different keys for exactly that reason — two grids sharing one slot is not a smaller demo, it is a broken one.
What a snapshot contains
GridStateSnapshot is a plain object, so it goes into localStorage, a URL
parameter or a database column without ceremony: sorts, filters,
quickFilter, columns, page. Restoring accepts a
Partial, so a snapshot with two keys in it is a valid one.
When persistColumns is active, do not put columns in your own saved
snapshot as well. The same data written to two slots drifts apart the first time a reader
resizes a column without saving a view. Let each tool own its slice: columns →
persistColumns; sorts, filters and page → getState().
setState({ columns }) is the one exception, and it does the right thing —
it writes through to persistColumns' key for you.
Grid state API
| Property | Type | Default | Description |
|---|---|---|---|
| grid.getState() | () => GridStateSnapshot | — | Current sorts, filters, quick filter, column layout and page as one serialisable object. |
| grid.setState(snap) | (snap: Partial<GridStateSnapshot>) => void | — | Restores a snapshot. sorts, filters or quickFilter trigger a refetch; a columns-only snapshot does not. |
| [initialState] | GridStateSnapshot | — | Applied once, before the first fetchRows() — the server sees the right params from request one. |
| (stateChanged) | EventEmitter<GridStateSnapshot> | — | Fires on every state change — the auto-save hook. Debounce it when writing to an API. |
| config.persistColumns | { mode: 'none' | 'local-storage' | 'session-storage' | 'server', key } | — | Automatic column width/order/pin/visibility persistence, in its own storage slot. server mode takes save/load observables instead of a key. |
| GridStateSnapshot.sorts | SortConfig[] | — | The active sorts. Restoring them refetches. |
| GridStateSnapshot.filters | FilterState | — | The active column filters, keyed by column. Restoring them refetches. |
| GridStateSnapshot.columns | ColumnState[] | — | Width, order, pin and visibility per column. Restoring them does not refetch. |
| GridStateSnapshot.page | number | — | 1-based current page, for paging mode. |