Skip to content

Grid State Persistence

Maya edited this page Nov 2, 2023 · 11 revisions

Revision history

Version User Date Notes
0.1 Hristo Anastasov 06.11.2019 Specification for State Persistence directive and API
0.2 Hristo Anastasov 06.11.2019 Specification for State Persistence directive and API
0.3 Hristo Anastasov 06.11.2019 Final version of API exposed.
0.4 Hristo Anastasov 19.11.2019 Refining return type and parameters of public methods.
0.5 Hristo Anastasov 28.05.2020 Add support for igxHierarchicalGrid and igxTreeGrid, support for expansion states
0.6 Maya Kirova 18.07.2022 Add support for igxPivotGrid by storing the pivotConfiguration
  • Radoslav Mirchev | Date:
  • Konstantin Dinev | Date:

Grid State Persistence Specification


  1. Overview
  2. User Stories
  3. Functionality
  4. API
  5. Assumptions and Limitations
  6. Angular elements implementation


The Grid State Persistence feature aims at providing an easy out-of-the-box way for developers to save/and restore the state of the IgxGrid, IgxTreeGrid, IgxHierarchicalGrid and the igxPivotGrid. Once the IgxGridState directive is applied, the developer will be able to get the current state of a feature or all features using getState method, and later apply it on the grid using setState method (see API).


  • Story 1. As a citizen developer, I want to get the grid state on API call.
  • Story 2. As a citizen developer, I want to pass an options object describing what features state are not needed to be saved.
  • Story 2. As a citizen developer, I want to get only the columns state or certain feature state on API call.
  • Story 3. As a citizen developer, I want to restore the state by passing in the state object retrieved by the getState method as an argument to the setState method.

End user:

  • Story 1: As an end user, I want to see the same grid state as I left it on my last visit of the page.

Acceptance criteria

  1. After applying the IgxGridState directive on the grid, calling getState method on the directive will return a serialized object implementing the IGridState, (ITreeGridState, IHierarchicalGridState yet to be aded) interface, containing:
  • sorting expressions
  • groupby expressions (only available for igxGrid)
  • filtering expressions
  • columns state (pinned, sortable, filterable, movable, hidden, summary, hasSummary, width, header) implementing the IColumnState interface:
interface IColumnState {
    field: string;
    header?: string;
    width?: string;
    dataType?: string;
    pinned?: boolean;
    sortable?: boolean;
    filterable?: boolean;
    movable?: true;
    hidden?: boolean;
  • selection state
  • paging state
  • row pinning (only available for igxGrid)
  • expansion states
  • row islands state (only for IgxHierarchicalGrid), implementing the IGridStateCollection interface: export interface IGridStateCollection { id: string; state: IGridState; }
  • pivot configuration state (only available for igxPivotGrid).
  1. After applying the IgxGridState directive, calling getState with a false argument will return a non-serialized object implementing the IGridState, (ITreeGridState, IHierarchicalGridState yet to be added) interface.

3.1. End User Experience The user experience is the same as user has applied sorting, filtering, etc, through the UI.

3.2. Developer Experience The developer is applying the IgxGridState directive on the grid, which allows working with the State Persistence API to easily retrieve/set the grid state.

Based on the use case, the developer may choose to apply the IgxGridState directive along with an optional options object implementing the IGridStateOptions interface:

interface IGridStateOptions {
    selection?: boolean;
    filtering?: boolean;
    advancedFiltering?: boolean;
    paging?: boolean;
    sorting?: boolean;
    groupby? : boolean;
    columns?: boolean;
    rowPinning?: Boolean;
    expansion? : Boolean;
    rowIslands? : boolean;
    pivotConfiguration?: IPivotConfiguration;
<igx-grid #grid [igxGridState]="options" [data]="localData" ></igx-grid>
@ViewChild(IgxGridStateDirective, { static: true }) public state;
public options = {
    selection: false,
    filtering: true,
    advancedFiltering: false,
    paging: true,
    sorting: true,
    groupby: false,
    columns: true

  public ngOnInit() { NavigationStart) => {


  public saveGridState() {
    const state = this.state.getState();
    // save `state` object to any database, localStorage, etc.

  public restoreGridState() {
      // retrieve `state` from the data storage

Every key/value pair in the IGridStateOptions indicates if a certain feature state will be saved/restored.

3.3. Globalization/Localization


3.4. User Interface


3.5. API


Name Description Type Default value Valid values
options Object containing the features which state to be saved/restored object IGridStateOptions
private _options: IGridStateOptions = {
    columns: true,
    filtering: true,
    advancedFiltering: true,
    sorting: true,
    groupby: true,
    paging: true,
    selection: true,
    pivotConfiguration: true


Name Description Return type Parameters
getState(params) Returns the current grid state in a serialized object, when called without arguments. Can be called with parameters to return the state only for a particular feature. Calling with a false serialize argument will return a non-serialized object. IGridState, string feature: string, string[], serialize: boolean
setState(gridState) Restores the grid state or a certain feature state from a state object, either serialized or non-serialized. void object: IGridState




Assumptions Limitation Notes
Filtering depends on knowing the column data types. If Filtering is enabled, columns are enabled too.
In case the state is stored and applied as string, custom functions and templates applied to any of the stored objects will not be restored out of the box.
This includes, but is not limited to:
- igxColumn functions and temples - fomatter, filters, summaries etc.
- Pivot Dimension and Value functions - memberFunction, formatter, styles, custom aggregator functions etc.
For such scenarios, the functions/templates need to be manually applied on the related initialization events - columnInit, dimensionInit, valueInit etc.


For the web components version of the grids, we've added an igc-grid-state component, which extends the existing directive's functionality.

Note: The component is not part of Angular's public API. It exist only for the web component version as a way to declaratively add the functionality to the web component's grid, since angular elements cannot wrap directives.

It can be declaratively added to any of the grid components as a child:

<igc-grid ...>
    <igc-grid-state id="state"></igc-grid-state>

And exposes the same API as the directive.

Clone this wiki locally