This section covers saving and restoring the grid state, such as the filter model, selected rows, etc.
Saving and Restoring State Copy Link
The following buttons log saving and restoring state to the developer console.
'use client';
import React, {
StrictMode,
useCallback,
useMemo,
useRef,
useState,
} from "react";
import { createRoot } from "react-dom/client";
import type {
AutoGroupColumnDef,
ColDef,
ColGroupDef,
GridPreDestroyedEvent,
GridState,
RowSelectionOptions,
StateUpdatedEvent,
Toolbar,
} from "ag-grid-community";
import { enableDevValidations } from "ag-grid-community";
import { AllEnterpriseModule } from "ag-grid-enterprise";
import { AgGridProvider, AgGridReact } from "ag-grid-react";
import type { IOlympicData } from "./interfaces";
import "./styles.css";
import { useFetchJson } from "./useFetchJson";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [AllEnterpriseModule];
const GridExample = () => {
const gridRef = useRef<AgGridReact<IOlympicData>>(null);
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [columnDefs, setColumnDefs] = useState<(ColDef | ColGroupDef)[]>([
{ field: "athlete", minWidth: 150 },
{ field: "age" },
{ field: "country", minWidth: 150 },
{
headerName: "Competition",
groupId: "competition",
children: [
{ field: "year" },
{ field: "date", minWidth: 150 },
{ field: "sport", minWidth: 150 },
],
},
{
headerName: "Medals",
groupId: "medals",
children: [
{ field: "gold" },
{ field: "silver", columnGroupShow: "open" },
{ field: "bronze", columnGroupShow: "open" },
{ field: "total", columnGroupShow: "closed" },
],
},
]);
const defaultColDef = useMemo<ColDef>(() => {
return {
flex: 1,
minWidth: 100,
filter: true,
enableRowGroup: true,
enablePivot: true,
enableValue: true,
headerNameEditable: true,
};
}, []);
const defaultColGroupDef = useMemo<Partial<ColGroupDef>>(() => {
return { headerNameEditable: true };
}, []);
const autoGroupColumnDef = useMemo<AutoGroupColumnDef>(() => {
return { minWidth: 200 };
}, []);
const rowSelection = useMemo<RowSelectionOptions>(
() => ({
mode: "multiRow",
}),
[],
);
const toolbar = useMemo<Toolbar>(
() => ({ items: ["agQuickFilterToolbarItem", "agFindToolbarItem"] }),
[],
);
const [initialState, setInitialState] = useState<GridState>();
const [currentState, setCurrentState] = useState<GridState>();
const [gridVisible, setGridVisible] = useState(true);
const { data, loading } = useFetchJson<IOlympicData>(
"https://www.ag-grid.com/example-assets/olympic-winners.json",
);
const reloadGrid = useCallback(() => {
setGridVisible(false);
setTimeout(() => {
setGridVisible(true);
});
}, []);
const onGridPreDestroyed = useCallback(
(params: GridPreDestroyedEvent<IOlympicData>) => {
const { state } = params;
console.log("Grid state on destroy (can be persisted)", state);
setInitialState(state);
},
[],
);
const onStateUpdated = useCallback(
(params: StateUpdatedEvent<IOlympicData>) => {
console.log("State updated", params.state);
setCurrentState(params.state);
},
[],
);
const printState = useCallback(() => {
console.log("Grid state", currentState);
}, [currentState]);
return (
<AgGridProvider modules={modules}>
<div style={containerStyle}>
<div className="example-wrapper">
<div>
<span className="button-group">
<button onClick={reloadGrid}>
Recreate Grid with Current State
</button>
<button onClick={printState}>Print State</button>
</span>
</div>
<div style={gridStyle}>
{gridVisible && (
<AgGridReact<IOlympicData>
ref={gridRef}
gridId="gridState"
rowData={data}
loading={loading}
columnDefs={columnDefs}
defaultColDef={defaultColDef}
defaultColGroupDef={defaultColGroupDef}
autoGroupColumnDef={autoGroupColumnDef}
sideBar={true}
toolbar={toolbar}
pagination={true}
rowSelection={rowSelection}
cellSelection={true}
calculatedColumns={true}
enableRowPinning={true}
suppressColumnMoveAnimation={true}
ensureDomOrder={true}
initialState={initialState}
onGridPreDestroyed={onGridPreDestroyed}
onStateUpdated={onStateUpdated}
/>
)}
</div>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
.example-wrapper {
display: flex;
flex-direction: column;
height: 100%;
}
#myGrid {
flex: 1 1 0px;
width: 100%;
}
.button-group {
padding-bottom: 4px;
display: inline-block;
font-family: Verdana, Geneva, Tahoma, sans-serif;
font-size: 13px;
}
.button-group > * {
margin-right: 4px;
}
export interface IOlympicData {
athlete: string,
age: number,
country: string,
year: number,
date: string,
sport: string,
gold: number,
silver: number,
bronze: number,
total: number
}import { useState, useEffect } from 'react';
/**
* Fetch example Json data
* Not recommended for production use!
*/
export const useFetchJson = <T,>(url:string, limit?: number) => {
const [data, setData] = useState<T[]>();
const [loading, setLoading] = useState(true);
useEffect(() => {
// StrictMode runs this effect twice: drop the superseded run's response rather than applying both.
let cancelled = false;
const fetchData = async () => {
setLoading(true);
// Note error handling is omitted here for brevity
const response = await fetch(url);
const json = await response.json();
const data = limit ? json.slice(0, limit) : json;
if (cancelled) {
return;
}
setData(data);
setLoading(false);
};
fetchData();
return () => {
cancelled = true;
};
}, [url, limit]);
return { data, loading };
};The initial state is provided via the grid option initialState. It is only read once when the grid is created.
const initialState = {
filter: {
filterModel: {
year: {
filterType: 'set',
values: ['2012'],
}
}
},
columnVisibility: {
hiddenColIds: ['athlete'],
},
rowGroup: {
groupColIds: ['athlete'],
}
};
<AgGridReact initialState={initialState} />The current grid state can be retrieved by listening to the state updated event, which is fired with the latest state when it changes, or via api.getState().
The state is also passed in the Grid Pre-Destroyed Event, which can be used to get the state when the grid is destroyed.
Invoked immediately before the grid is destroyed. This is useful for cleanup logic that needs to run before the grid is torn down. |
Grid state has been updated. |
State Contents Copy Link
The grid state is made up of the sections below, each of which can be provided or omitted independently. If applying some but not all of the column state properties, then initialState.partialColumnState must be set to true.
partialColumnState controls which column state sections you supply, not whether those sections may themselves be partial. Any section you include must match its documented shape.
The state also contains the grid version number. When applying state with older version numbers, any old state properties will be automatically migrated to the current format.
The grid state is designed to be serialisable, so any functions will be stripped out. For example, aggregation functions should be Registered as Custom Functions to work with state rather than being set as Directly Applied Functions.
Properties available on the GridState interface.
Grid version number |
Aggregation Functions (column state) |
Opened Column Groups, and column group header names edited by end users |
Column Order (column state) |
Left/right Pinned Columns (column state) |
Column Sizes - width/flex (column state) |
Hidden Columns (column state) |
Column Header Names edited by end users (column state) |
Column Filters and Advanced Filter |
Find search value and active match. Works for Client-Side Row Model only, and only when the Quick Access Toolbar is configured with agFindToolbarItem; otherwise the findSearchValue grid option is the only source
|
Quick Filter search text. Only captured and restored when the Quick Access Toolbar is configured with agQuickFilterToolbarItem; otherwise the quickFilterText grid option is the only source
|
Currently focused cell. Works for Client-Side Row Model only |
Current page |
Currently manually pinned rows |
Current pivot mode and pivot columns, and pivot column label sort (column state) |
Currently selected cell ranges |
Current Row Group Columns (column state) |
Currently expanded group rows |
Currently expanded Server-Side Row Model group rows when using ssrmExpandAllAffectsAllRows |
Currently selected rows. For Server-Side Row Model, will be ServerSideRowSelectionState | ServerSideRowGroupSelectionState, for other row models, will be an array of row IDs. Can only be set for Client-Side Row Model and Server-Side Row Model.
|
Current scroll position. Works for Client-Side Row Model only |
Current Side Bar positioning and opened tool panel, including the state of each open tool panel |
Current sort columns and direction (column state) |
The per-column "Show Values As" mode (column state) |
Columns the user created or removed at runtime, such as Calculated Columns, along with the column definition properties they changed. Unlike the other sections, which configure existing columns, this section can create and remove them.
|
When providing a partial initialState with some but not all column state properties, set this to true. This controls which top-level sections are supplied, not whether a section may itself be partial: any section you provide must match its documented shape. Not required if passing the whole state object retrieved from the grid. Not used for api.setState(), as that instead takes a second argument of properties to ignore.
|
When restoring the current page using the Server Side Row Model or Infinite Row Model, additional configuration is required:
- For the Server Side Row Model - set the
serverSideInitialRowCountproperty to a value which includes the rows to be shown. - For the Infinite Row Model - set the
infiniteInitialRowCountproperty to a value which includes the rows to be shown.
Column and Group IDs Copy Link
Give every column a colId or a field, and every column group a groupId. Without them, state can be restored onto the wrong column.
Columns are identified in the state by their Column ID, and Column Groups by their groupId. These IDs are the only link between a saved state and the columns it describes, so they need to mean the same thing when the state is restored as they did when it was saved.
A column that provides neither colId nor field - one using only a valueGetter, for example - is given a positional ID instead. That ID follows the column's position in columnDefs rather than the column itself. If the definitions are reordered between saving and restoring, each column's state is applied to whichever column now occupies its old position.
This affects every column state section: sizes, sort, pinning, visibility, order and header names. A restored grid can silently show another column's width, or a header the user renamed on the wrong column.
Column groups behave the same way. A group definition without a groupId is given a generated ID which changes when the column definitions change, so the open / closed state of that group may not be restored.
Setting State Copy Link
The best way to restore grid state is via initial state as described above. However, it is also possible to restore state on an existing grid via api.setState(state).
setState should only be used to restore grid state. The grid does not support being used as a controlled component, so do not call this on every state update.
It is possible to maintain the existing state for individual state contents by passing a second argument to setState that contains the top-level properties to ignore. E.g. api.setState(state, ['filter']) will maintain the existing filter state in the grid.
Anything the provided state omits is reset rather than left as is. For example, a state without a quickFilter section clears the quick filter value in the toolbar.
'use client';
import React, {
StrictMode,
useCallback,
useMemo,
useRef,
useState,
} from "react";
import { createRoot } from "react-dom/client";
import type {
AutoGroupColumnDef,
ColDef,
ColGroupDef,
GridPreDestroyedEvent,
GridReadyEvent,
GridState,
RowSelectionOptions,
StateUpdatedEvent,
Toolbar,
} from "ag-grid-community";
import { enableDevValidations } from "ag-grid-community";
import { AllEnterpriseModule } from "ag-grid-enterprise";
import { AgGridProvider, AgGridReact } from "ag-grid-react";
import type { IOlympicData } from "./interfaces";
import "./styles.css";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [AllEnterpriseModule];
const GridExample = () => {
const gridRef = useRef<AgGridReact<IOlympicData>>(null);
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [rowData, setRowData] = useState<IOlympicData[]>();
const [columnDefs, setColumnDefs] = useState<(ColDef | ColGroupDef)[]>([
{ field: "athlete", minWidth: 150 },
{ field: "age" },
{ field: "country", minWidth: 150 },
{
headerName: "Competition",
groupId: "competition",
children: [
{ field: "year" },
{ field: "date", minWidth: 150 },
{ field: "sport", minWidth: 150 },
],
},
{
headerName: "Medals",
groupId: "medals",
children: [
{ field: "gold" },
{ field: "silver", columnGroupShow: "open" },
{ field: "bronze", columnGroupShow: "open" },
{ field: "total", columnGroupShow: "closed" },
],
},
]);
const defaultColDef = useMemo<ColDef>(() => {
return {
flex: 1,
minWidth: 100,
filter: true,
enableRowGroup: true,
enablePivot: true,
enableValue: true,
headerNameEditable: true,
};
}, []);
const defaultColGroupDef = useMemo<Partial<ColGroupDef>>(() => {
return { headerNameEditable: true };
}, []);
const autoGroupColumnDef = useMemo<AutoGroupColumnDef>(() => {
return { minWidth: 200 };
}, []);
const toolbar = useMemo<Toolbar>(
() => ({ items: ["agQuickFilterToolbarItem", "agFindToolbarItem"] }),
[],
);
const rowSelection = useMemo<RowSelectionOptions>(
() => ({
mode: "multiRow",
}),
[],
);
const [currentState, setCurrentState] = useState<GridState>();
const [gridVisible, setGridVisible] = useState(true);
const [savedState, setSavedState] = useState<GridState>();
const onGridReady = useCallback((params: GridReadyEvent<IOlympicData>) => {
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data: IOlympicData[]) => setRowData(data));
}, []);
const reloadGrid = useCallback(() => {
setGridVisible(false);
setTimeout(() => {
setRowData(undefined);
setGridVisible(true);
});
}, []);
const onGridPreDestroyed = useCallback(
(params: GridPreDestroyedEvent<IOlympicData>) => {
const { state } = params;
console.log("Grid state on destroy (can be persisted)", state);
},
[],
);
const onStateUpdated = useCallback(
(params: StateUpdatedEvent<IOlympicData>) => {
console.log("State updated", params.state);
setCurrentState(params.state);
},
[],
);
const printState = useCallback(() => {
console.log("Grid state", currentState);
}, [currentState]);
const saveState = useCallback(() => {
console.log("Saved state", currentState);
setSavedState(currentState);
}, [currentState]);
const setState = useCallback(() => {
if (savedState) {
gridRef.current!.api.setState(savedState);
console.log("Set state", savedState);
}
}, [savedState]);
return (
<AgGridProvider modules={modules}>
<div style={containerStyle}>
<div className="example-wrapper">
<div>
<span className="button-group">
<button onClick={saveState}>Save State</button>
<button onClick={reloadGrid}>Recreate Grid with No State</button>
<button onClick={setState}>Set State</button>
<button onClick={printState}>Print State</button>
</span>
</div>
<div style={gridStyle}>
{gridVisible && (
<AgGridReact<IOlympicData>
ref={gridRef}
gridId="setState"
rowData={rowData}
columnDefs={columnDefs}
defaultColDef={defaultColDef}
defaultColGroupDef={defaultColGroupDef}
autoGroupColumnDef={autoGroupColumnDef}
sideBar={true}
toolbar={toolbar}
pagination={true}
rowSelection={rowSelection}
cellSelection={true}
calculatedColumns={true}
enableRowPinning={true}
suppressColumnMoveAnimation={true}
onGridReady={onGridReady}
onGridPreDestroyed={onGridPreDestroyed}
onStateUpdated={onStateUpdated}
/>
)}
</div>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
.example-wrapper {
display: flex;
flex-direction: column;
height: 100%;
}
#myGrid {
flex: 1 1 0px;
width: 100%;
}
.button-group {
padding-bottom: 4px;
display: inline-block;
font-family: Verdana, Geneva, Tahoma, sans-serif;
font-size: 13px;
}
.button-group > * {
margin-right: 4px;
}
export interface IOlympicData {
athlete: string,
age: number,
country: string,
year: number,
date: string,
sport: string,
gold: number,
silver: number,
bronze: number,
total: number
} Converting Column State to Grid State Copy Link
State retrieved via the Column State APIs can be converted into grid state via the helper functions convertColumnState and convertColumnGroupState.
const state = {
...convertColumnState(columnState),
...convertColumnGroupState(columnGroupState)
};