Grid State Persistence & Grid-Type-Specific Operations

View on GitHub

Part of the igniteui-angular-grids skill hub. For grid import patterns and viewChild access — see data-operations.md. For Tree Grid / Hierarchical Grid / Pivot Grid / Grid Lite setup — see types.md. For paging and remote data — see paging-remote.md.

State Persistence
Tree Grid Data Operations
Hierarchical Grid Data Operations
Pivot Grid Data Operations
Grid Lite Data Operations
Key Rules

State Persistence

Saving and Restoring Grid State

Use IgxGridStateDirective to persist sorting, filtering, grouping, paging, selection, and column state:

<igx-grid #grid [data]="data()" igxGridState>
  <igx-column field="name" [sortable]="true" [filterable]="true" [groupable]="true"></igx-column>
</igx-grid>

import { IgxGridStateDirective } from 'igniteui-angular/grids/core';

export class StatefulGridComponent {
  gridState = viewChild.required(IgxGridStateDirective);

  saveState() {
    const state = this.gridState().getState();
    localStorage.setItem('gridState', state);
  }

  restoreState() {
    const state = localStorage.getItem('gridState');
    if (state) {
      this.gridState().setState(state);
    }
  }
}

Selective State Features

Control which features are persisted:

<igx-grid #grid [data]="data()" [igxGridState]="stateOptions">
</igx-grid>

stateOptions = {
  sorting: true,
  filtering: true,
  groupBy: true,
  paging: true,
  columns: true,
  cellSelection: false,    // skip selection state
  rowSelection: false,
  columnSelection: false,
  advancedFiltering: true,
  rowPinning: true,
  expansion: true
};

IgxGridState does not persist functions — this includes sorting strategies, filtering strategies, column formatters, summaries, cellClasses, and cellStyles. Use the stateParsed event to reapply these after restoring state:

restoreState() {
  const stateJson = localStorage.getItem('gridState');
  if (!stateJson) return;

  // Subscribe to stateParsed to reapply custom strategies before state is applied
  this.gridState().stateParsed.pipe(take(1)).subscribe(parsedState => {
    parsedState.sorting?.forEach(expr => expr.strategy = NoopSortingStrategy.instance());
  });

  this.gridState().setState(stateJson);
}

Restoring Column Templates

Column templates are also not serialized. Use the columnInit event to reassign them:

@ViewChild('activeTemplate', { static: true }) public activeTemplate: TemplateRef<any>;

onColumnInit(column: IgxColumnComponent) {
  if (column.field === 'IsActive') {
    column.bodyTemplate = this.activeTemplate;
  }
}

<igx-grid #grid [data]="data()" igxGridState (columnInit)="onColumnInit($event)">
  <ng-template #activeTemplate igxCell let-val="val">
    <igx-checkbox [checked]="val"></igx-checkbox>
  </ng-template>
</igx-grid>

Tree Grid Data Operations

Recursive Filtering Behavior

Tree Grid filtering is inclusive — when a child matches, all its ancestors are kept visible (marked as isFilteredOutParent) and auto-expanded. This is the default TreeGridFilteringStrategy.

<igx-tree-grid #treeGrid
  [data]="employees()"
  [primaryKey]="'id'"
  [foreignKey]="'managerId'"
  [allowFiltering]="true"
  [filterMode]="'excelStyleFilter'"
  height="600px">
  <igx-column field="name" [filterable]="true" [sortable]="true"></igx-column>
  <igx-column field="title" [filterable]="true"></igx-column>
</igx-tree-grid>

When you filter for title = 'Developer', all ancestor rows are shown even though they don't match, and they're auto-expanded so you can see the matching children in context.

Per-Level Sorting

Tree Grid sorting is applied within each parent level — children are sorted among siblings, not globally flattened:

// This sorts employees within their respective manager, not globally
this.treeGridRef().sort({ fieldName: 'name', dir: SortingDirection.Asc, ignoreCase: true });

Tree Grid Batch Editing

Tree Grid uses HierarchicalTransactionService — each transaction carries a path array tracing the parent hierarchy, enabling proper undo/redo of nested changes:

<igx-tree-grid #treeGrid
  [data]="employees()"
  [primaryKey]="'id'"
  [foreignKey]="'managerId'"
  [batchEditing]="true"
  [rowEditable]="true"
  height="600px">
  <igx-column field="name" [editable]="true"></igx-column>
</igx-tree-grid>

// Add a row as child of a specific parent
this.treeGridRef().addRow({ id: 100, name: 'New Employee', managerId: 2 }, 2);

// Cascade delete — deleting a parent removes all descendants (default behavior)
this.treeGridRef().deleteRow(2); // deletes row 2 and all its children

Hierarchical Grid Data Operations

Independent Grid Levels

Each level of a hierarchical grid has its own independent sorting, filtering, and paging state. Configure features on the <igx-row-island> blueprint:

<igx-hierarchical-grid #hGrid
  [data]="companies()"
  [primaryKey]="'id'"
  [allowFiltering]="true"
  [filterMode]="'excelStyleFilter'"
  height="600px">

  <igx-column field="name" [sortable]="true" [filterable]="true"></igx-column>

  <!-- Each row island defines column/feature config for that level -->
  <igx-row-island [key]="'orders'" [primaryKey]="'orderId'" [allowFiltering]="true" [rowEditable]="true">
    <igx-column field="orderId" [sortable]="true" [filterable]="true"></igx-column>
    <igx-column field="amount" dataType="number" [editable]="true"></igx-column>

    <igx-paginator [perPage]="10"></igx-paginator>
  </igx-row-island>
</igx-hierarchical-grid>

Accessing Child Grid Instances

To perform programmatic operations on child grids, use the (gridCreated) event:

onChildGridCreated(event: IGridCreatedEventArgs) {
  const childGrid = event.grid;
  // Example: apply a default sort to all child grids
  childGrid.sort({ fieldName: 'orderId', dir: SortingDirection.Desc, ignoreCase: false });
}

<igx-row-island [key]="'orders'" (gridCreated)="onChildGridCreated($event)">
  <igx-column field="orderId" [sortable]="true"></igx-column>
</igx-row-island>

Batch Editing Propagation

Setting [batchEditing]="true" on the root hierarchical grid automatically propagates to all child grids:

<igx-hierarchical-grid #hGrid
  [data]="companies()"
  [primaryKey]="'id'"
  [batchEditing]="true"
  [rowEditable]="true">
  <!-- All child grids inherit batchEditing automatically -->
  <igx-row-island [key]="'departments'" [primaryKey]="'deptId'" [rowEditable]="true">
    <igx-column field="name" [editable]="true"></igx-column>
  </igx-row-island>
</igx-hierarchical-grid>

NOTE: Each child grid instance has its own TransactionService. Commits must be done per grid instance.

Pivot Grid Data Operations

IMPORTANT: The Pivot Grid does NOT use standard sorting, filtering, editing, or paging APIs. All data operations are controlled through pivotConfiguration.

Dimension-Based Filtering

import { FilteringExpressionsTree, FilteringLogic, IgxStringFilteringOperand } from 'igniteui-angular/core';

// Create a filter for a dimension
const regionFilter = new FilteringExpressionsTree(FilteringLogic.Or);
regionFilter.filteringOperands = [
  {
    fieldName: 'Region',
    condition: IgxStringFilteringOperand.instance().condition('equals'),
    searchVal: 'North America'
  },
  {
    fieldName: 'Region',
    condition: IgxStringFilteringOperand.instance().condition('equals'),
    searchVal: 'Europe'
  }
];

// Apply the filter to a dimension and notify the grid
this.pivotConfig.filters[0].filter = regionFilter;
this.pivotGridRef().notifyDimensionChange(true);

Dimension-Based Sorting

// Sort a row dimension via the public API
this.pivotGridRef().sortDimension(this.pivotConfig.rows[0], SortingDirection.Desc);

Key Pivot Grid Limitations

No cell/row editing, batch editing, or row adding
No paging
No column pinning, moving, or hiding (columns are auto-generated)
No row dragging
No standard filtering (allowFiltering is forced to false)
No GroupBy (grouping is inherent via dimensions)
State persistence serializes the full pivotConfiguration

Grid Lite Data Operations

Grid Lite sorting, filtering, remote data, events, and limitations are fully documented in types.md. Refer to that file for all Grid Lite data operations — this section intentionally avoids duplicating that content.

Key differences from Flat/Tree/Hierarchical Grid APIs:

Uses IgxGridLiteSortingExpression / IgxGridLiteFilteringExpression (NOT ISortingExpression / FilteringExpressionsTree)

Uses dataPipelineConfiguration for remote ops (NOT noop strategies + events)

Has no editing, grouping, paging, summaries, selection, state persistence, or export

Key Rules

State persistence — use IgxGridStateDirective to save/restore sort, filter, group, and column configuration; functions (formatters, strategies, summaries) must be reapplied via stateParsed event
Tree Grid filtering is recursive — parents of matching children are always shown and auto-expanded
Hierarchical Grid levels are independent — sorting/filtering/paging don't cascade; configure on <igx-row-island>
Pivot Grid is read-only — no editing, paging, or standard filtering/sorting; use pivotConfiguration for all data operations
Grid Lite has its own API — uses IgxGridLiteSortingExpression/IgxGridLiteFilteringExpression (NOT ISortingExpression/FilteringExpressionsTree), dataPipelineConfiguration for remote ops (NOT noop strategies), and has no editing, grouping, paging, summaries, or selection
Use the correct component type for viewChild — IgxGridLiteComponent, IgxGridComponent, IgxTreeGridComponent, IgxHierarchicalGridComponent, or IgxPivotGridComponent
Import the correct directives/components — IGX_GRID_DIRECTIVES, IGX_TREE_GRID_DIRECTIVES, IGX_HIERARCHICAL_GRID_DIRECTIVES, IGX_PIVOT_GRID_DIRECTIVES, or individual Grid Lite imports (with CUSTOM_ELEMENTS_SCHEMA)
Use signals for data — [data]="myData()" with signal<T[]>([])