Home/Data & State/Grid State
Data & State

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.

First Name
Last Name
Department
Salary ($)
Status
Sam
Williams
Engineering
110000
Inactive
Uma
Garcia
Engineering
110000
Active
Wendy
Wilson
Engineering
110000
Active
Yara
Anderson
Engineering
110000
Active
Alice
Harris
Engineering
110000
Active
Carol
Lee
Engineering
110000
Active
Iris
Williams
Engineering
100000
Active
Kate
Garcia
Engineering
100000
Inactive
Mia
Wilson
Engineering
100000
Active
Olivia
Anderson
Engineering
100000
Active
Quinn
White
Engineering
100000
Active
Sam
Lewis
Engineering
100000
Active
Yara
Johnson
Engineering
90000
Active
Alice
Garcia
Engineering
90000
Active
Carol
Wilson
Engineering
90000
Inactive
Emma
Anderson
Engineering
90000
Active
Grace
White
Engineering
90000
Active
Iris
Lewis
Engineering
90000
Active
Olivia
Johnson
Engineering
80000
Active
Quinn
Jones
Engineering
80000
Active
20 / 50 records

[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.

First Name
Last Name
Department
Salary ($)
Status
Alice
Smith
Engineering
40000
Inactive
Bob
Smith
Marketing
41000
Active
Carol
Smith
Sales
42000
Active
David
Smith
HR
43000
Active
Emma
Smith
Finance
44000
Active
Frank
Smith
Operations
45000
Active
Grace
Smith
Design
46000
Active
Henry
Smith
Legal
47000
Inactive
Iris
Smith
Product
48000
Active
Jack
Smith
Support
49000
Active
Kate
Smith
Engineering
50000
Active
Liam
Smith
Marketing
51000
Active
Mia
Smith
Sales
52000
Active
Noah
Smith
HR
53000
Active
Olivia
Smith
Finance
54000
Inactive
Paul
Smith
Operations
55000
Active
Quinn
Smith
Design
56000
Active
Rachel
Smith
Legal
57000
Active
Sam
Smith
Product
58000
Active
Tara
Smith
Support
59000
Active
20 / 500 records

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.

First Name
Last Name
Department
Salary ($)
Status
Alice
Smith
Engineering
40000
Inactive
Bob
Smith
Marketing
41000
Active
Carol
Smith
Sales
42000
Active
David
Smith
HR
43000
Active
Emma
Smith
Finance
44000
Active
Frank
Smith
Operations
45000
Active
Grace
Smith
Design
46000
Active
Henry
Smith
Legal
47000
Inactive
Iris
Smith
Product
48000
Active
Jack
Smith
Support
49000
Active
Kate
Smith
Engineering
50000
Active
Liam
Smith
Marketing
51000
Active
Mia
Smith
Sales
52000
Active
Noah
Smith
HR
53000
Active
Olivia
Smith
Finance
54000
Inactive
Paul
Smith
Operations
55000
Active
Quinn
Smith
Design
56000
Active
Rachel
Smith
Legal
57000
Active
Sam
Smith
Product
58000
Active
Tara
Smith
Support
59000
Active
20 / 500 records
Last written to 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.
  • persistColumns writes 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.

FeatureSavesHow
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

PropertyTypeDefaultDescription
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.sortsSortConfig[]—The active sorts. Restoring them refetches.
GridStateSnapshot.filtersFilterState—The active column filters, keyed by column. Restoring them refetches.
GridStateSnapshot.columnsColumnState[]—Width, order, pin and visibility per column. Restoring them does not refetch.
GridStateSnapshot.pagenumber—1-based current page, for paging mode.