Grid Structure

June 24, 2026 · View on GitHub

Part of the igniteui-angular-grids skill hub. For grid type selection, imports, and feature availability — see the hub. For editing, grouping, summaries, toolbar, export — see features.md. For Tree Grid, Hierarchical Grid, Grid Lite, Pivot Grid specifics — see types.md. For programmatic data operations — see data-operations.md.

Contents

Quick Start

Imports

AGENT INSTRUCTION: Check package.json to determine whether the project uses igniteui-angular or @infragistics/igniteui-angular. Always import from the specific entry point of whichever package is installed. Never import from the root barrel of either package.

// Open-source package — import from specific entry points
import { IgxGridComponent, IGX_GRID_DIRECTIVES } from 'igniteui-angular/grids/grid';

// Licensed package — same entry-point structure, different prefix
// import { IgxGridComponent, IGX_GRID_DIRECTIVES } from '@infragistics/igniteui-angular/grids/grid';

// AVOID — never import from the root barrel (wrong for BOTH variants)
// import { IgxGridComponent } from 'igniteui-angular';
// import { IgxGridComponent } from '@infragistics/igniteui-angular';

import { Component, ChangeDetectionStrategy, signal, viewChild } from '@angular/core';

@Component({
  selector: 'app-users-grid',
  imports: [IGX_GRID_DIRECTIVES],
  templateUrl: './users-grid.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class UsersGridComponent {
  // Signal-based view child — use #grid on the template element
  gridRef = viewChild.required<IgxGridComponent>('grid');

  protected users = signal<User[]>([]);
}

Basic Grid

<igx-grid #grid
  [data]="users()"
  [primaryKey]="'id'"
  [autoGenerate]="false"
  height="600px"
  width="100%">

  <igx-column field="id" header="ID" [hidden]="true"></igx-column>
  <igx-column field="name" header="Name" [sortable]="true" [filterable]="true" [resizable]="true"></igx-column>
  <igx-column field="email" header="Email" [sortable]="true" [filterable]="true"></igx-column>
  <igx-column field="role" header="Role" [groupable]="true" [filterable]="true"></igx-column>
  <igx-column field="salary" header="Salary" dataType="number" [hasSummary]="true"></igx-column>
  <igx-column field="hireDate" header="Hire Date" dataType="date" [sortable]="true"></igx-column>
  <igx-column field="active" header="Active" dataType="boolean"></igx-column>

</igx-grid>

Column Configuration

Data Types

Set dataType to enable proper formatting, filtering, sorting, and editing:

dataTypeBehavior
stringText input, string filtering
numberNumeric input, number filtering, number summaries
booleanCheckbox editor, boolean filtering
dateDate picker editor, date filtering
dateTimeDate+time editor
timeTime picker editor
currencyCurrency formatting, number filtering
percentPercentage formatting
imageImage rendering (read-only)

Column Templates

Override default rendering with template directives:

<igx-column field="status" header="Status">
  <!-- Custom cell template -->
  <ng-template igxCell let-cell="cell">
    <igx-badge [type]="cell.value === 'Active' ? 'success' : 'error'">
      {{ cell.value }}
    </igx-badge>
  </ng-template>

  <!-- Custom header template -->
  <ng-template igxHeader let-column>
    <igx-icon>verified</igx-icon> {{ column.header }}
  </ng-template>

  <!-- Custom editor template -->
  <ng-template igxCellEditor let-cell="cell">
    <igx-select [(ngModel)]="cell.editValue">
      <igx-select-item value="Active">Active</igx-select-item>
      <igx-select-item value="Inactive">Inactive</igx-select-item>
    </igx-select>
  </ng-template>

  <!-- Custom filter cell template -->
  <ng-template igxFilterCellTemplate let-column="column">
    <input (input)="onCustomFilter($event, column)" />
  </ng-template>

  <!-- Custom summary template -->
  <ng-template igxSummary let-summaryResults>
    Active: {{ getActiveCount(summaryResults) }}
  </ng-template>
</igx-column>

Column Groups

Group columns under a shared header:

<igx-column-group header="Personal Info">
  <igx-column field="firstName" header="First Name"></igx-column>
  <igx-column field="lastName" header="Last Name"></igx-column>
</igx-column-group>

<igx-column-group header="Contact">
  <igx-column field="email" header="Email"></igx-column>
  <igx-column field="phone" header="Phone"></igx-column>
</igx-column-group>

Multi-Row Layout (MRL)

Create complex cell layouts spanning multiple rows/columns:

<igx-column-layout>
  <igx-column field="name" [rowStart]="1" [colStart]="1" [colEnd]="3"></igx-column>
  <igx-column field="email" [rowStart]="2" [colStart]="1"></igx-column>
  <igx-column field="phone" [rowStart]="2" [colStart]="2"></igx-column>
</igx-column-layout>

Column Pinning

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

Or programmatically: this.gridRef().pinColumn('name').

Sorting

<igx-grid
  [data]="data()"
  [(sortingExpressions)]="sortExprs"
  [sortingOptions]="{ mode: 'multiple' }">
  <igx-column field="name" [sortable]="true"></igx-column>
</igx-grid>

Programmatic sorting:

this.gridRef().sort({ fieldName: 'name', dir: SortingDirection.Asc, ignoreCase: true });
this.gridRef().clearSort();

Events: (sorting) (cancelable), (sortingDone).

For advanced programmatic sorting patterns, custom sort strategies, and sorting events — see data-operations.md.

Filtering

Quick Filter (Row Filter)

<igx-grid [allowFiltering]="true" [filterMode]="'quickFilter'">
  <igx-column field="name" [filterable]="true"></igx-column>
</igx-grid>

Excel-Style Filter

<igx-grid [allowFiltering]="true" [filterMode]="'excelStyleFilter'">
  <igx-column field="name" [filterable]="true"></igx-column>
</igx-grid>

Advanced Filtering Dialog

<igx-grid [allowAdvancedFiltering]="true">
  <!-- Advanced filtering UI is shown via toolbar or API -->
</igx-grid>

Programmatic Filtering

this.gridRef().filter('name', 'John', IgxStringFilteringOperand.instance().condition('contains'), true);
this.gridRef().clearFilter('name');
this.gridRef().clearFilter(); // clear all

Events: (filtering) (cancelable), (filteringDone).

For advanced programmatic filtering, complex AND/OR trees, and remote filtering patterns — see data-operations.md.

Selection

Row Selection

<igx-grid [rowSelection]="'multiple'" [primaryKey]="'id'" [(selectedRows)]="selectedIds">
  <!-- Optional: Custom row selector checkbox -->
  <ng-template igxRowSelector let-rowContext>
    <igx-checkbox [checked]="rowContext.selected" [readonly]="true">
    </igx-checkbox>
  </ng-template>
</igx-grid>

Modes: 'none', 'single', 'multiple', 'multipleCascade' (tree grids).

Cell Selection

<igx-grid [cellSelection]="'multiple'"></igx-grid>

Column Selection

<igx-grid [columnSelection]="'multiple'">
  <igx-column field="name" [selectable]="true"></igx-column>
</igx-grid>

Events: (rowSelectionChanging), (columnSelectionChanging), (selected) (cell).

Key Rules

  1. Pick the right grid type first — see the hub for the decision guide
  2. Always set [primaryKey] — required for editing, selection, row operations (Flat, Tree, Hierarchical, Pivot grids; NOT Grid Lite)
  3. 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
  4. Use the right component type for viewChild — IgxGridLiteComponent, IgxGridComponent, IgxTreeGridComponent, IgxHierarchicalGridComponent, or IgxPivotGridComponent
  5. Set [autoGenerate]="false" and define columns explicitly for production grids (except Pivot Grid where columns are auto-generated)
  6. Set dataType on every column for correct filtering, sorting, editing, and summaries
  7. Use signals for data binding — [data]="myData()" with signal<T[]>([])
  8. Virtualization is automatic — don't wrap grids in virtual scroll containers
  9. Omit width on generated <igx-column> elements. Columns without width equally share available grid width. Only set width when the user explicitly asks for fixed or percentage column sizing. If column widths are used, at least one column must not have a specified width so that it fills the remaining space in the grid.

See Also