From 364a19cbbf1bb91b17164458bed0dfe67e4e2445 Mon Sep 17 00:00:00 2001 From: mstoyanova Date: Mon, 1 Jun 2026 11:47:07 +0300 Subject: [PATCH 1/6] feat(grid-migration): add migration guide from Grid Lite to Premium Data Grid --- .../references/grid-migration.md | 481 ++++++++++++++++++ 1 file changed, 481 insertions(+) create mode 100644 skills/igniteui-angular-grids/references/grid-migration.md diff --git a/skills/igniteui-angular-grids/references/grid-migration.md b/skills/igniteui-angular-grids/references/grid-migration.md new file mode 100644 index 00000000000..b933d8e1484 --- /dev/null +++ b/skills/igniteui-angular-grids/references/grid-migration.md @@ -0,0 +1,481 @@ +# Ignite UI for Angular - Grid Lite → Premium Data Grid Migration + +> **Part of the [`igniteui-angular-grids`](../SKILL.md) skill hub.** + +## Purpose + +This skill automates the migration from the **open-source Grid Lite** (`igx-grid-lite`, MIT licensed) to the **Premium Data Grid** (`igx-grid`, commercially licensed). Use it when a project outgrows Grid Lite's read-only capabilities and needs enterprise features such as editing, selection, paging, grouping, summaries, export, or state persistence. + +## MANDATORY AGENT PROTOCOL + +> **DO NOT write any code from memory.** Grid APIs change between versions. + +Before producing migration code: + +1. **Identify the current Grid Lite usage** - read the user's existing component files to understand their column configuration, templates, data binding, and any `dataPipelineConfiguration` usage. +2. **Consult the grids skill** - read the relevant reference files from [`igniteui-angular-grids`](../igniteui-angular-grids/SKILL.md) for the target features the user needs after migration. +3. **Use the MCP server** - call `mcp_igniteui-cli_get_doc` or `mcp_igniteui-cli_search_docs` for Angular to verify current API details when in doubt. +4. **Only then produce output** - base all code on verified references, not memory. + +--- + +## When to Migrate + +Migrate from Grid Lite to the Premium Grid when the user needs **any** of these features: + +| Required Feature | Grid Lite | Premium Grid | +|---|---|---| +| Cell / Row / Batch editing | No | Yes | +| Row adding / deleting | No | Yes | +| Row / Cell / Column selection | No | Yes | +| Paging (client or remote) | No | Yes | +| GroupBy | No | Yes (exclusive to flat grid) | +| Summaries (built-in & custom) | No | Yes | +| Column pinning | No | Yes | +| Column moving | No | Yes | +| Master-Detail rows | No | Yes (exclusive to flat grid) | +| Export (Excel / CSV) | No | Yes | +| Toolbar | No | Yes | +| State persistence | No | Yes | +| Advanced filtering | No | Yes | +| Action strip | No | Yes | +| Row drag | No | Yes | +| Clipboard support | No | Yes | +| Cell merging | No | Yes | + +> **IMPORTANT:** The upgrade path from Grid Lite is **always** to `igx-grid` (`IgxGridComponent`). Never recommend a different component type as a substitute. + +--- + +## Migration Checklist + +### Step 1 - Install / Verify the Premium Package + +Grid Lite uses the separate `igniteui-grid-lite` npm package. The Premium Grid is part of the main `igniteui-angular` (or `@infragistics/igniteui-angular`) package. + +> **AGENT INSTRUCTION:** Check `package.json` to determine which package variant is installed. If only `igniteui-grid-lite` is present, the user needs to install the full package. + +```bash +# Open-source package +npm install igniteui-angular + +# OR licensed package (requires private registry) +npm install @infragistics/igniteui-angular +``` + +The `igniteui-grid-lite` package can be removed after migration if no other Grid Lite instances remain: + +```bash +npm uninstall igniteui-grid-lite +``` + +### Step 2 - Update Imports + +**Before (Grid Lite):** + +```typescript +import { + IgxGridLiteComponent, + IgxGridLiteColumnComponent, + IgxGridLiteCellTemplateDirective, + IgxGridLiteHeaderTemplateDirective, +} from 'igniteui-angular/grids/lite'; +``` + +**After (Premium Grid):** + +```typescript +// Open-source +import { IgxGridComponent, IGX_GRID_DIRECTIVES } from 'igniteui-angular/grids/grid'; + +// Licensed +// import { IgxGridComponent, IGX_GRID_DIRECTIVES } from '@infragistics/igniteui-angular/grids/grid'; +``` + +> **Key change:** The Premium Grid provides `IGX_GRID_DIRECTIVES` - a single convenience import that includes all grid directives (columns, templates, toolbar, paginator bindings, etc.). You no longer need to import each directive individually. + +### Step 3 - Update the Component Decorator + +**Before:** + +```typescript +@Component({ + selector: 'app-data-view', + imports: [ + IgxGridLiteComponent, + IgxGridLiteColumnComponent, + IgxGridLiteCellTemplateDirective, + ], + schemas: [CUSTOM_ELEMENTS_SCHEMA], // Required by Grid Lite + templateUrl: './data-view.component.html', + changeDetection: ChangeDetectionStrategy.OnPush, +}) +``` + +**After:** + +```typescript +@Component({ + selector: 'app-data-view', + imports: [IGX_GRID_DIRECTIVES], + // No CUSTOM_ELEMENTS_SCHEMA needed - Premium Grid is a native Angular component + templateUrl: './data-view.component.html', + changeDetection: ChangeDetectionStrategy.OnPush, +}) +``` + +**Changes:** +- Replace individual Grid Lite imports with `IGX_GRID_DIRECTIVES` +- Remove `CUSTOM_ELEMENTS_SCHEMA` from `schemas` (Grid Lite is a Web Component wrapper; the Premium Grid is a native Angular component) +- Remove the `schemas` array entirely if it only contained `CUSTOM_ELEMENTS_SCHEMA` + +### Step 4 - Update the Component Class + +**Before:** + +```typescript +export class DataViewComponent { + gridRef = viewChild>('grid'); + data: Product[] = []; +} +``` + +**After:** + +```typescript +export class DataViewComponent { + gridRef = viewChild.required('grid'); + protected data = signal([]); +} +``` + +**Changes:** +- Replace `IgxGridLiteComponent` with `IgxGridComponent` +- Add `[primaryKey]` support - strongly recommended for editing, selection, and any row-targeted API (`getRowByKey`, transactions, row pinning, etc.). Without it the grid falls back to row indexes/object identity, which breaks across virtualization and remote data. +- Use `signal()` for reactive data (recommended but not required) + +### Step 5 - Update the Template + +#### Selector & Grid Element + +| Grid Lite | Premium Grid | +|---|---| +| `` | `` (needs an explicit `height` - or a parent with a fixed height - for row virtualization) | +| `` | `` | +| No `[primaryKey]` | `[primaryKey]="'id'"` (strongly recommended for editing/selection/row APIs) | +| `[sortingOptions]="{ mode: 'multiple' }"` | `[sortingOptions]="{ mode: 'multiple' }"` or per-column `[sortable]="true"` | + +**Before:** + +```html + + + + + + +``` + +**After:** + +```html + + + + + + + +``` + +#### Column Attribute Differences + +| Grid Lite attribute | Premium Grid equivalent | Notes | +|---|---|---| +| `sortable` (boolean HTML attr) | `[sortable]="true"` or bare `sortable` | Both styles work on `igx-column`; bracketed binding is preferred for clarity | +| `filterable` (boolean HTML attr) | `[filterable]="true"` or bare `filterable` | Same pattern | +| `resizable` (boolean HTML attr) | `[resizable]="true"` or bare `resizable` | Same pattern | +| `hidden` (boolean HTML attr) | `[hidden]="true"` | Use binding - bare `hidden` collides with the native HTML attribute | +| `field` | `field` | Identical | +| `header` | `header` | Identical | +| `dataType` | `dataType` | Premium supports additional types: `dateTime`, `time`, `currency`, `percent`, `image` | +| `width` | `width` | Identical (CSS value, e.g., `'250px'`) | + +#### Cell Template Migration + +**Before (Grid Lite):** + +```html + + + {{ value }} + + +``` + +**After (Premium Grid):** + +```html + + + {{ cell.value }} + + +``` + +**Key differences:** +- Template directive: `igxGridLiteCell` → `igxCell` +- Context object: Grid Lite exposes `let-value` directly; Premium exposes `let-cell="cell"` where you access `cell.value`, `cell.row`, `cell.column` +- Premium also supports `igxCellEditor` for edit templates (not available in Grid Lite) + +#### Header Template Migration + +**Before:** + +```html + + {{ column.header }} + +``` + +**After:** + +```html + + {{ column.header }} + +``` + +**Change:** `igxGridLiteHeader` → `igxHeader` + +### Step 6 - Migrate Remote Data Operations + +Grid Lite uses `dataPipelineConfiguration` (async callbacks). The Premium Grid uses **noop data operation strategies + events**. + +**Before (Grid Lite - `dataPipelineConfiguration`):** + +```typescript +dataPipeline: IgxGridLiteDataPipelineConfiguration = { + sort: async (params) => { + return await this.dataService.sortRemote(params.grid.sortingExpressions); + }, + filter: async (params) => { + return await this.dataService.filterRemote(params.grid.filteringExpressions); + }, +}; +``` + +```html + + +``` + +**After (Premium Grid - noop strategies + events):** + +```typescript +import { + NoopSortingStrategy, + NoopFilteringStrategy, +} from 'igniteui-angular/core'; +import { ISortingEventArgs } from 'igniteui-angular/grids/core'; + +export class DataViewComponent { + gridRef = viewChild.required('grid'); + noopSort = NoopSortingStrategy.instance(); + noopFilter = NoopFilteringStrategy.instance(); + + onSortingDone(event: ISortingEventArgs) { + this.dataService.sortRemote(this.gridRef().sortingExpressions).subscribe(data => this.data.set(data)); + } + + onFilteringDone() { + this.dataService.filterRemote(this.gridRef().filteringExpressionsTree).subscribe(data => this.data.set(data)); + } +} +``` + +```html + + +``` + +### Step 7 - Migrate Sort/Filter Events + +| Grid Lite Event | Premium Grid Event | Notes | +|---|---|---| +| `(sorting)` | `(sorting)` | Both cancelable | +| `(sorted)` | `(sortingDone)` | Name changed | +| `(filtering)` | `(filtering)` | Both cancelable | +| `(filtered)` | `(filteringDone)` | Name changed | + +### Step 8 - Migrate Programmatic Sort/Filter API + +**Grid Lite API:** + +```typescript +this.gridRef().sort({ key: 'name', direction: 'ascending' }); +this.gridRef().filter({ key: 'age', condition: 'greaterThan', searchTerm: 21 }); +this.gridRef().clearSort(); +this.gridRef().clearFilter(); +``` + +**Premium Grid API:** + +```typescript +import { SortingDirection, IgxNumberFilteringOperand } from 'igniteui-angular/core'; + +// Sorting +this.gridRef().sort({ fieldName: 'name', dir: SortingDirection.Asc, ignoreCase: true }); +this.gridRef().clearSort('name'); + +// Filtering +this.gridRef().filter('age', 21, IgxNumberFilteringOperand.instance().condition('greaterThan')); +this.gridRef().clearFilter('age'); +``` + +**Key differences:** +- Sort expression: `key` → `fieldName`, `direction: 'ascending'` → `dir: SortingDirection.Asc` +- Filter: object-based → positional arguments with typed operand instances + +### Step 9 - Remove Grid Lite Artifacts + +After migration, clean up: + +1. Remove `CUSTOM_ELEMENTS_SCHEMA` from any component that only used it for Grid Lite +2. Remove `import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'` if no longer needed +3. Remove `igniteui-grid-lite` from `package.json` if no Grid Lite instances remain +4. Remove any `IgxGridLiteDataPipelineConfiguration` types and replace with noop strategies + +--- + +## Adding Enterprise Features Post-Migration + +Once on the Premium Grid, enable the features that motivated the migration: + +### Editing + +```html + + + + +``` + +### Selection + +```html + + + +``` + +### Paging + +```html + + + + +``` + +### GroupBy + +```html + + + +``` + +### Export + +```typescript +import { IgxExcelExporterService, IgxExcelExporterOptions } from 'igniteui-angular/grids/core'; + +export class DataViewComponent { + private excelExporter = inject(IgxExcelExporterService); + + exportToExcel() { + this.excelExporter.exportData(this.data(), new IgxExcelExporterOptions('export')); + } +} +``` + +### Toolbar + +```html + + + Products + + + + + + + + +``` + +### Summaries + +```html + +``` + +### Batch Editing + +```html + + + +``` + +```typescript +// Commit or discard all pending changes +this.gridRef().transactions.commit(this.data()); +this.gridRef().transactions.clear(); +``` + +--- + +## Quick Reference - Full Migration Map + +| Aspect | Grid Lite | Premium Grid | +|---|---|---| +| **Package** | `igniteui-grid-lite` (separate) | `igniteui-angular` or `@infragistics/igniteui-angular` | +| **Entry point** | `igniteui-angular/grids/lite` | `igniteui-angular/grids/grid` | +| **Component** | `IgxGridLiteComponent` | `IgxGridComponent` | +| **Selector** | `` | `` | +| **Column selector** | `` | `` | +| **Imports style** | Individual (`IgxGridLiteComponent`, `IgxGridLiteColumnComponent`, ...) | Bundle (`IGX_GRID_DIRECTIVES`) | +| **Schema** | `CUSTOM_ELEMENTS_SCHEMA` required | Not needed | +| **Primary key** | Not supported | `[primaryKey]="'id'"` (required for editing/selection) | +| **Cell template** | `igxGridLiteCell` (exposes `let-value`) | `igxCell` (exposes `let-cell="cell"`, access `cell.value`) | +| **Header template** | `igxGridLiteHeader` | `igxHeader` | +| **Editor template** | Not available | `igxCellEditor` | +| **Column attributes** | Boolean HTML attrs (`sortable`, `filterable`) | Angular inputs (`[sortable]="true"`, `[filterable]="true"`) | +| **Remote data** | `dataPipelineConfiguration` (async callbacks) | Noop strategies + events | +| **Sort event (done)** | `(sorted)` | `(sortingDone)` | +| **Filter event (done)** | `(filtered)` | `(filteringDone)` | +| **Sort expression** | `{ key, direction }` | `{ fieldName, dir: SortingDirection }` | +| **License** | MIT (free) | Commercial (trial with watermark) | + +--- + +## Related Skills + +- **[`igniteui-angular-grids`](../igniteui-angular-grids/SKILL.md)** - Full grid reference for all grid types (use after migration for feature details) +- **[`igniteui-angular-theming`](../igniteui-angular-theming/SKILL.md)** - Theming and styling (works with both Grid Lite and Premium Grid) +- **[`igniteui-angular-components`](../igniteui-angular-components/SKILL.md)** - Non-grid UI components From da2c0eddd12b0210f3332a973bf9862c69592e35 Mon Sep 17 00:00:00 2001 From: Marina Stoyanova Date: Mon, 1 Jun 2026 14:43:02 +0300 Subject: [PATCH 2/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/igniteui-angular-grids/references/grid-migration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/igniteui-angular-grids/references/grid-migration.md b/skills/igniteui-angular-grids/references/grid-migration.md index b933d8e1484..a363910c18a 100644 --- a/skills/igniteui-angular-grids/references/grid-migration.md +++ b/skills/igniteui-angular-grids/references/grid-migration.md @@ -476,6 +476,6 @@ this.gridRef().transactions.clear(); ## Related Skills -- **[`igniteui-angular-grids`](../igniteui-angular-grids/SKILL.md)** - Full grid reference for all grid types (use after migration for feature details) -- **[`igniteui-angular-theming`](../igniteui-angular-theming/SKILL.md)** - Theming and styling (works with both Grid Lite and Premium Grid) -- **[`igniteui-angular-components`](../igniteui-angular-components/SKILL.md)** - Non-grid UI components +- **[`igniteui-angular-grids`](../SKILL.md)** - Full grid reference for all grid types (use after migration for feature details) +- **[`igniteui-angular-theming`](../../igniteui-angular-theming/SKILL.md)** - Theming and styling (works with both Grid Lite and Premium Grid) +- **[`igniteui-angular-components`](../../igniteui-angular-components/SKILL.md)** - Non-grid UI components From aab50b23d1c2f0d763e92650c6deb9a48e0a1bcc Mon Sep 17 00:00:00 2001 From: Marina Stoyanova Date: Mon, 1 Jun 2026 14:43:38 +0300 Subject: [PATCH 3/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/igniteui-angular-grids/references/grid-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/igniteui-angular-grids/references/grid-migration.md b/skills/igniteui-angular-grids/references/grid-migration.md index a363910c18a..0ca753bc91a 100644 --- a/skills/igniteui-angular-grids/references/grid-migration.md +++ b/skills/igniteui-angular-grids/references/grid-migration.md @@ -13,7 +13,7 @@ This skill automates the migration from the **open-source Grid Lite** (`igx-grid Before producing migration code: 1. **Identify the current Grid Lite usage** - read the user's existing component files to understand their column configuration, templates, data binding, and any `dataPipelineConfiguration` usage. -2. **Consult the grids skill** - read the relevant reference files from [`igniteui-angular-grids`](../igniteui-angular-grids/SKILL.md) for the target features the user needs after migration. +2. **Consult the grids skill** - read the relevant reference files from [`igniteui-angular-grids`](../SKILL.md) for the target features the user needs after migration. 3. **Use the MCP server** - call `mcp_igniteui-cli_get_doc` or `mcp_igniteui-cli_search_docs` for Angular to verify current API details when in doubt. 4. **Only then produce output** - base all code on verified references, not memory. From 1d6846e47ee81cd162e576a5f62714895c9de68e Mon Sep 17 00:00:00 2001 From: Konstantin Dinev Date: Mon, 1 Jun 2026 16:01:58 +0300 Subject: [PATCH 4/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/igniteui-angular-grids/references/grid-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/igniteui-angular-grids/references/grid-migration.md b/skills/igniteui-angular-grids/references/grid-migration.md index 0ca753bc91a..1e7f1720f53 100644 --- a/skills/igniteui-angular-grids/references/grid-migration.md +++ b/skills/igniteui-angular-grids/references/grid-migration.md @@ -106,7 +106,7 @@ import { IgxGridComponent, IGX_GRID_DIRECTIVES } from 'igniteui-angular/grids/gr IgxGridLiteColumnComponent, IgxGridLiteCellTemplateDirective, ], - schemas: [CUSTOM_ELEMENTS_SCHEMA], // Required by Grid Lite + schemas: [CUSTOM_ELEMENTS_SCHEMA], // Optional: only needed when using the underlying web component directly templateUrl: './data-view.component.html', changeDetection: ChangeDetectionStrategy.OnPush, }) From 4ef02d2bdf915704be17ea02b383b80ba1141a70 Mon Sep 17 00:00:00 2001 From: Konstantin Dinev Date: Mon, 1 Jun 2026 16:02:15 +0300 Subject: [PATCH 5/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/igniteui-angular-grids/references/grid-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/igniteui-angular-grids/references/grid-migration.md b/skills/igniteui-angular-grids/references/grid-migration.md index 1e7f1720f53..938e0cc425d 100644 --- a/skills/igniteui-angular-grids/references/grid-migration.md +++ b/skills/igniteui-angular-grids/references/grid-migration.md @@ -126,7 +126,7 @@ import { IgxGridComponent, IGX_GRID_DIRECTIVES } from 'igniteui-angular/grids/gr **Changes:** - Replace individual Grid Lite imports with `IGX_GRID_DIRECTIVES` -- Remove `CUSTOM_ELEMENTS_SCHEMA` from `schemas` (Grid Lite is a Web Component wrapper; the Premium Grid is a native Angular component) +- If you previously added `CUSTOM_ELEMENTS_SCHEMA` for Grid Lite (e.g. when using the underlying web component directly), remove it after migrating — Premium Grid is a native Angular component - Remove the `schemas` array entirely if it only contained `CUSTOM_ELEMENTS_SCHEMA` ### Step 4 - Update the Component Class From 658e9480a57f294bf92ff79f73009e5469b0a251 Mon Sep 17 00:00:00 2001 From: Konstantin Dinev Date: Mon, 1 Jun 2026 16:02:30 +0300 Subject: [PATCH 6/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- skills/igniteui-angular-grids/references/grid-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/igniteui-angular-grids/references/grid-migration.md b/skills/igniteui-angular-grids/references/grid-migration.md index 938e0cc425d..8668a1a0afb 100644 --- a/skills/igniteui-angular-grids/references/grid-migration.md +++ b/skills/igniteui-angular-grids/references/grid-migration.md @@ -460,7 +460,7 @@ this.gridRef().transactions.clear(); | **Selector** | `` | `` | | **Column selector** | `` | `` | | **Imports style** | Individual (`IgxGridLiteComponent`, `IgxGridLiteColumnComponent`, ...) | Bundle (`IGX_GRID_DIRECTIVES`) | -| **Schema** | `CUSTOM_ELEMENTS_SCHEMA` required | Not needed | +| **Schema** | `CUSTOM_ELEMENTS_SCHEMA` (optional; only if using the underlying web component directly) | Not needed | | **Primary key** | Not supported | `[primaryKey]="'id'"` (required for editing/selection) | | **Cell template** | `igxGridLiteCell` (exposes `let-value`) | `igxCell` (exposes `let-cell="cell"`, access `cell.value`) | | **Header template** | `igxGridLiteHeader` | `igxHeader` |