New to Kendo UI for AngularStart a free 30-day trial

Managing the Angular Data Grid State

The Grid provides built-in state management functionality that allows you to save and restore the state across sessions.

This is particularly useful in scenarios where you may navigate away from the Grid or refresh the page, and you want to ensure that your preferences are preserved. For example, if you are working with a large dataset and have applied specific filters, sorting, or grouping, you can return to the same view without having to reapply all the settings.

The following example demonstrates the state persistence feature of the Grid where the settings are saved in the local storage.

Change Theme
Theme
Loading ...

You can persist the following data operations and column settings of the Grid:

FeatureDescription
SortingShows the data in the same order, so users don’t need to sort again.
FilteringKeeps filters in place, so users always see the data they care about.
GroupingRemembers how data was grouped to make it easy to understand again.
PagingOpens the same page the user was last on, saving time.
Column VisibilityHides or shows the same columns the user picked before.
Columns OrderKeeps the columns in the same order the user arranged them.
Columns WidthKeeps the same column sizes for easy reading.
Sticky ColumnsKeeps the sticky state of the columns
Locked ColumnsKeeps important columns in view.

Saving the Grid State

The Grid automatically saves the settings in the currentState field when binding data through the kendoGridBinding directive.

The currentState is updated whenever the Grid's configuration changes. Such changes include data operations like sorting, filtering, grouping, and paging, as well as column settings like resizing, reordering, and hiding/showing columns.

The following code snippet demonstrates how to access the current state of the Grid and save it to local storage.

ts
public saveState(grid: GridComponent): void {
   const gridState: GridState = grid.currentState;
   localStorage.setItem("grid-state", JSON.stringify(state));
}

Saving the Grid State with data Binding

When using the data property to bind the Grid, you need to manually save the current state. This is done by handling the gridStateChange event which is emitted whenever the Grid's configuration changes.

html
<kendo-grid (gridStateChange)="onStateChange($event)" ...>
    ...
</kendo-grid>

The event handler receives a GridState object as an argument, which contains the current Grid settings. You can use this object to save the state to local storage or any other storage mechanism of your choice.

ts
public currentState: GridState;
public onStateChange(state: GridState): void {
   this.currentState = state
}
public saveState(): void {
   localStorage.setItem("grid-state", JSON.stringify(this.currentState));
}

Restoring the Grid State

You can reload the saved preferences using the loadState method of the Grid. The method accepts the GridState object as an argument and applies the saved configuration, ensuring the Grid looks exactly as it was left.

The following code snippet demonstrates how to restore the Grid state from local storage.

ts
@ViewChild(GridComponent) grid: GridComponent;
public restoreGridState(): void {
  const state: GridState = JSON.parse(localStorage.getItem("grid-state"));
  this.grid.loadState(state);
}

Restoring the Grid State with data Binding

When using data binding to bind the Grid, you need to manually apply the data operations state to the data source, using the process method from the Data Query package. More details can be found in the Handling Data Operations article.

ts
public state: GridState;
public restoreGridState(){
  this.gridData = process(products, {
    sort: this.state.sort,
    filter: this.state.filter,
    group: this.state.group,
  });
}

Undo and Redo the Grid State

With the undo and redo functionality, you can easily revert or reapply changes made to the Grid's configuration.

This feature is especially useful when you want to experiment with different settings, such as sorting, filtering, or grouping, without worrying about losing your previous configurations. By enabling undo and redo, you can seamlessly navigate between states, improving your workflow and productivity.

The Grid provides multiple options to enable Undo and Redo functionality, including built-in tools, a customizable history stack, and programmatic methods for advanced use cases. The following sections outline these options in detail.

Built-in Undo and Redo

The Grid provides built-in undo and redo toolbar tools, allows you to easily revert or reapply previous states.

The following example demonstrates the undo and redo functionality of the Grid.

Change Theme
Theme
Loading ...

To enable the undo and redo buttons functionality:

  1. Apply the kendoGridUndoRedo directive to the Grid.

  2. Add the Undo and Redo toolbar button tools and apply the kendoGridUndoTool and kendoGridRedoTool directives to them.

    html
    <kendo-grid kendoGridUndoRedo>
        <kendo-toolbar>
            <kendo-toolbar-button kendoGridUndoTool></button>
            <kendo-toolbar-button kendoGridRedoTool></button>
        </kendo-toolbar>
    </kendo-grid>

History Stack

The undo and redo functionality uses a history stack to manage the Grid's state. Each configuration change (e.g., sorting, filtering, grouping) pushes the current state onto the stack. Clicking Undo reverts to the last state by popping it from the stack, while Redo reapplies a previously undone state by pushing it back onto the stack.

You can customize the number of states stored in the history stack by setting the maxStoredStates property. By default, the Grid stores up to 10 states in the history stack, but you can adjust this value to suit your application's needs.

html
<kendo-grid kendoGridUndoRedo [maxStoredStates]="40" ...>
    <kendo-grid-toolbar>
        <button kendoButton kendoGridUndoTool>Undo</button>
        <button kendoButton kendoGridRedoTool>Redo</button>
    </kendo-grid-toolbar>
</kendo-grid>

Custom Undo and Redo

To provide your own undo and redo buttons or implement a more complex undo/redo functionality, you can use the undo and redo methods of the kendoGridUndoRedo directive. This directive provides access to the underlying undo and redo functionality of the Grid, allowing you to further customize the behavior.

  1. Apply the kendoGridUndoRedo directive to the Grid and reference its instance using a template variable. In the following code snippet, the template variable is named undoRedo.

    html
    <kendo-grid kendoGridUndoRedo #undoRedo="kendoGridUndoRedo" ...></kendo-grid>
  2. Use the instance from the first step to call the undo and redo methods and revert or reapply changes to the Grid's configuration.

    html
    <button kendoButton (click)="undoRedo.undo()">Undo</button>
    <button kendoButton (click)="undoRedo.redo()">Redo</button>

Known Limitations

  • The built-in state management APIs - the currentState getter, the gridStateChange event, and the undo/redo functionality rely on cloning the current Grid data. If any data item has a property that points to a function, cloning the object will trigger a JavaScript error.