igniteui-cli 15.5.0 → 15.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/package.json +4 -4
  2. package/templates/blazor/igb/projects/ai-config/files/skills/AGENTS.md +6 -3
  3. package/templates/blazor/igb/projects/ai-config/files/skills/README.md +30 -45
  4. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/SKILL.md +48 -96
  5. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/charts.md +61 -238
  6. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/data-display.md +60 -193
  7. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/feedback.md +36 -92
  8. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +66 -224
  9. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout-manager.md +39 -88
  10. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout.md +75 -152
  11. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +40 -149
  12. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/SKILL.md +58 -243
  13. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +89 -280
  14. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +143 -431
  15. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/SKILL.md +91 -157
  16. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/data-operations.md +50 -228
  17. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +61 -222
  18. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/features.md +67 -360
  19. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/grid-migration.md +55 -236
  20. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/paging-remote.md +53 -202
  21. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/sizing.md +31 -232
  22. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/state.md +27 -119
  23. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/structure.md +88 -363
  24. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/types.md +87 -415
  25. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/SKILL.md +86 -0
  26. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +220 -0
  27. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/SKILL.md +83 -211
  28. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/common-patterns.md +93 -184
  29. package/templates/react/igr-ts/projects/_base/files/src/main.tsx +1 -0
  30. package/templates/react/igr-ts/projects/_base_with_home/files/src/app/home/style.module.css +3 -3
  31. package/templates/react/igr-ts/projects/ai-config/files/skills/README.md +30 -83
  32. package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
  33. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
  34. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
  35. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
  36. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
  37. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
  38. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
  39. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
  40. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
  41. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
  42. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
  43. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
  44. package/templates/react/igr-ts/projects/side-nav/files/src/app/app.css +9 -9
  45. package/templates/react/igr-ts/projects/side-nav/files/src/app/home/style.module.css +7 -7
  46. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/app.css +8 -8
  47. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Login.module.css +1 -69
  48. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Login.tsx +5 -5
  49. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/LoginBar.module.css +5 -26
  50. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/LoginDialog.module.css +0 -1
  51. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Register.module.css +1 -56
  52. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/components/Register.tsx +2 -2
  53. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/Profile.module.css +11 -11
  54. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectFacebook.tsx +1 -1
  55. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectGoogle.tsx +1 -1
  56. package/templates/react/igr-ts/projects/side-nav-auth/files/src/app/authentication/pages/RedirectMicrosoft.tsx +1 -1
  57. package/templates/react/igr-ts/projects/side-nav-mini/files/src/app/app.css +9 -9
  58. package/templates/react/igr-ts/projects/side-nav-mini/files/src/app/home/style.module.css +7 -7
  59. package/templates/react/igr-ts/projects/side-nav-mini-auth/files/src/app/app.css +7 -7
  60. package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
  61. package/templates/webcomponents/igc-ts/constants.js +5 -5
  62. package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
  63. package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
  64. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
  65. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
  66. package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
  67. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
  68. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
  69. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
  70. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
  71. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
  72. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
  73. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
  74. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
  75. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
  76. package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/component-mapping.md +0 -132
@@ -1,126 +1,64 @@
1
1
  # Paging, Remote Data & Virtualization
2
2
 
3
- > **Part of the [`igniteui-blazor-grids`](../SKILL.md) skill hub.**
4
- > For grid setup and column configuration — see [`structure.md`](./structure.md).
5
-
6
- ## Contents
7
-
8
- - [Paging with `IgbPaginator`](#paging-with-igbpaginator)
9
- - [Remote Paging](#remote-paging)
10
- - [Remote Data Operations](#remote-data-operations)
11
- - [Virtualization](#virtualization)
12
- - [Key Rules](#key-rules)
13
-
14
- ---
15
-
16
3
  ## Paging with `IgbPaginator`
17
4
 
18
- The grid does not have built-in paging. Instead, place an `IgbPaginator` component inside the grid:
19
-
20
- ### Basic paging
5
+ Paging is not a grid parameter — place an `IgbPaginator` **inside** the grid as a child component.
21
6
 
22
7
  ```razor
23
- <IgbGrid Data="data" PrimaryKey="Id" AutoGenerate="false"
24
- Width="100%" Height="500px">
25
- <IgbColumn Field="Id" Header="ID" />
8
+ <IgbGrid @ref="grid" Data="data" PrimaryKey="Id" Width="100%" Height="500px">
26
9
  <IgbColumn Field="Name" Header="Name" />
27
- <IgbColumn Field="Department" Header="Department" />
28
- <IgbPaginator PerPage="10" />
29
- </IgbGrid>
30
- ```
31
-
32
- ### Paginator parameters
33
-
34
- | Parameter | Type | Default | Description |
35
- |---|---|---|---|
36
- | `PerPage` | `double` | `15` | Rows per page |
37
- | `TotalRecords` | `double` | - | Total record count (required for remote paging) |
38
- | `SelectOptions` | `double[]` | `[5, 10, 15, 25, 50]` | Page size dropdown options |
39
-
40
- ### Paginator events
41
-
42
- | Event | Type | Description |
43
- |---|---|---|
44
- | `PerPageChange` | `EventCallback<IgbNumberEventArgs>` | Fires when page size changes |
45
- | `PageChange` | `EventCallback<IgbNumberEventArgs>` | Fires when current page changes |
46
- | `PagingDone` | `EventCallback<IgbPageEventArgs>` | Fires after paging completes |
47
-
48
- ### Programmatic paging
49
-
50
- ```razor
51
- <IgbGrid @ref="grid" Data="data" PrimaryKey="Id">
52
10
  <IgbPaginator @ref="paginator" PerPage="10" />
53
- ...
54
11
  </IgbGrid>
55
12
 
56
- <IgbButton @onclick="GoToFirstPage">First Page</IgbButton>
57
- <IgbButton @onclick="GoToNextPage">Next Page</IgbButton>
58
-
59
13
  @code {
60
14
  private IgbGrid grid = default!;
61
15
  private IgbPaginator paginator = default!;
62
16
 
63
- private async Task GoToFirstPage()
64
- {
65
- await paginator.PaginateAsync(0);
66
- }
67
-
68
- private async Task GoToNextPage()
69
- {
70
- await paginator.NextPageAsync();
71
- }
17
+ private Task First() => paginator.PaginateAsync(0); // 0-based page index
18
+ private Task Next() => paginator.NextPageAsync();
19
+ private Task Prev() => paginator.PreviousPageAsync();
72
20
  }
73
21
  ```
74
22
 
75
- ### Paginator navigation methods
23
+ | Parameter | Type | Default | Purpose |
24
+ |---|---|---|---|
25
+ | `PerPage` | `double` | `15` | Rows per page |
26
+ | `TotalRecords` | `double` | — | Server-side total; required for remote paging |
27
+ | `SelectOptions` | `double[]` | `[5, 10, 15, 25, 50]` | Page-size dropdown |
76
28
 
77
- | Method | Description |
78
- |---|---|
79
- | `PaginateAsync(double page)` | Go to a specific page (0-based index) |
80
- | `NextPageAsync()` | Go to the next page |
81
- | `PreviousPageAsync()` | Go to the previous page |
29
+ Events: `PageChange` and `PerPageChange` (`IgbNumberEventArgs`), `PagingDone` (`IgbPageEventArgs`).
82
30
 
83
- ---
31
+ The Pivot Grid does not support paging.
84
32
 
85
- ## Remote Paging
33
+ ## Remote paging
86
34
 
87
- When data lives on a server, fetch only the current page:
35
+ Bind `Data` to just the current page and tell the paginator the true total.
88
36
 
89
37
  ```razor
90
- <IgbGrid @ref="grid" Data="currentPageData" PrimaryKey="Id"
91
- AutoGenerate="false" Width="100%" Height="500px">
92
- <IgbColumn Field="Id" Header="ID" />
38
+ <IgbGrid Data="currentPageData" PrimaryKey="Id" AutoGenerate="false" Width="100%" Height="500px">
93
39
  <IgbColumn Field="Name" Header="Name" />
94
- <IgbColumn Field="Department" Header="Department" />
95
- <IgbPaginator PerPage="@pageSize"
96
- TotalRecords="@totalRecords"
97
- PageChange="OnPageChange"
98
- PerPageChange="OnPerPageChange" />
40
+ <IgbPaginator PerPage="@pageSize" TotalRecords="@totalRecords"
41
+ PageChange="OnPageChange" PerPageChange="OnPerPageChange" />
99
42
  </IgbGrid>
100
43
 
101
44
  @code {
102
- private IgbGrid grid = default!;
103
45
  private List<Employee> currentPageData = new();
104
- private int totalRecords = 0;
46
+ private int totalRecords, currentPage;
105
47
  private int pageSize = 20;
106
- private int currentPage = 0;
107
48
 
108
- protected override async Task OnInitializedAsync()
109
- {
110
- await LoadPageAsync();
111
- }
49
+ protected override Task OnInitializedAsync() => LoadPageAsync();
112
50
 
113
- private async Task OnPageChange(IgbNumberEventArgs args)
51
+ private Task OnPageChange(IgbNumberEventArgs args)
114
52
  {
115
53
  currentPage = (int)args.Detail;
116
- await LoadPageAsync();
54
+ return LoadPageAsync();
117
55
  }
118
56
 
119
- private async Task OnPerPageChange(IgbNumberEventArgs args)
57
+ private Task OnPerPageChange(IgbNumberEventArgs args)
120
58
  {
121
59
  pageSize = (int)args.Detail;
122
60
  currentPage = 0;
123
- await LoadPageAsync();
61
+ return LoadPageAsync();
124
62
  }
125
63
 
126
64
  private async Task LoadPageAsync()
@@ -133,103 +71,46 @@ When data lives on a server, fetch only the current page:
133
71
  }
134
72
  ```
135
73
 
136
- ### Key points for remote paging
137
-
138
- 1. **Set `TotalRecords`** on the paginator - this tells it the total number of records on the server.
139
- 2. **Bind `Data` to the current page** - only the current page's data is in memory.
140
- 3. **Handle `PageChange` and `PerPageChange`** - fetch new data from the server on each event.
141
-
142
- ---
74
+ Without `TotalRecords` the paginator cannot compute the page count and paging silently misbehaves.
143
75
 
144
- ## Remote Data Operations
76
+ ## Remote sorting and filtering
145
77
 
146
- For large datasets, disable client-side sorting/filtering and handle them on the server.
147
-
148
- ### Remote sorting
78
+ Handle `SortingDone` and `FilteringDone`, translate the expressions into a server query, and reassign `Data`. In production, fold paging, sorting, and filtering into one request rather than reloading per event.
149
79
 
150
80
  ```razor
151
- <IgbGrid @ref="grid" Data="data" PrimaryKey="Id"
152
- SortingDone="OnSortingDone">
153
- <IgbColumn Field="Name" Sortable="true" />
154
- <IgbColumn Field="Department" Sortable="true" />
81
+ <IgbGrid Data="data" PrimaryKey="Id" Height="600px" AllowFiltering="true"
82
+ SortingDone="OnSortingDone" FilteringDone="OnFilteringDone">
83
+ <IgbColumn Field="Name" Sortable="true" Filterable="true" />
155
84
  <IgbColumn Field="Salary" Sortable="true" DataType="GridColumnDataType.Number" />
156
- <IgbPaginator PerPage="@pageSize" TotalRecords="@totalRecords"
157
- PageChange="OnPageChange" />
85
+ <IgbPaginator PerPage="@pageSize" TotalRecords="@totalRecords" PageChange="OnPageChange" />
158
86
  </IgbGrid>
159
87
 
160
88
  @code {
161
- private IgbGrid grid = default!;
162
89
  private List<Employee> data = new();
163
- private int totalRecords = 0;
90
+ private int totalRecords, currentPage;
164
91
  private int pageSize = 20;
165
- private int currentPage = 0;
166
92
  private IgbSortingExpression[]? currentSort;
93
+ private IgbFilteringExpressionsTree? currentFilter;
167
94
 
168
- private async Task OnSortingDone(IgbSortingExpressionEventArgs args)
95
+ private Task OnSortingDone(IgbSortingExpressionEventArgs args)
169
96
  {
170
97
  currentSort = args.Detail;
171
98
  currentPage = 0;
172
- await LoadDataAsync();
173
- }
174
-
175
- private async Task OnPageChange(IgbNumberEventArgs args)
176
- {
177
- currentPage = (int)args.Detail;
178
- await LoadDataAsync();
99
+ return LoadDataAsync();
179
100
  }
180
101
 
181
- private async Task LoadDataAsync()
102
+ private Task OnFilteringDone(IgbFilteringExpressionsTreeEventArgs args)
182
103
  {
183
- var result = await Api.GetEmployeesAsync(
184
- page: currentPage,
185
- pageSize: pageSize,
186
- sortField: currentSort?.FirstOrDefault()?.FieldName,
187
- sortDir: currentSort?.FirstOrDefault()?.Dir.ToString()
188
- );
189
- data = result.Items;
190
- totalRecords = result.TotalCount;
191
- StateHasChanged();
104
+ currentFilter = args.Detail;
105
+ currentPage = 0;
106
+ return LoadDataAsync();
192
107
  }
193
- }
194
- ```
195
-
196
- ### Remote filtering
197
-
198
- ```razor
199
- <IgbGrid @ref="grid" Data="data" PrimaryKey="Id"
200
- AllowFiltering="true"
201
- FilteringDone="OnFilteringDone">
202
- <IgbColumn Field="Name" Filterable="true" DataType="GridColumnDataType.String" />
203
- <IgbColumn Field="Department" Filterable="true" DataType="GridColumnDataType.String" />
204
- </IgbGrid>
205
-
206
- @code {
207
- private IgbGrid grid = default!;
208
- private List<Employee> data = new();
209
108
 
210
- private async Task OnFilteringDone(IgbFilteringExpressionsTreeEventArgs args)
109
+ private Task OnPageChange(IgbNumberEventArgs args)
211
110
  {
212
- // Extract filter information and send to server
213
- var filterDetail = args.Detail;
214
- var result = await Api.GetEmployeesFilteredAsync(filterDetail);
215
- data = result.Items;
216
- StateHasChanged();
111
+ currentPage = (int)args.Detail;
112
+ return LoadDataAsync();
217
113
  }
218
- }
219
- ```
220
-
221
- ### Combined remote operations pattern
222
-
223
- For production apps, combine paging, sorting, and filtering into a single server call:
224
-
225
- ```razor
226
- @code {
227
- private int currentPage = 0;
228
- private int pageSize = 20;
229
- private int totalRecords = 0;
230
- private IgbSortingExpression[]? currentSort;
231
- private string? filterField;
232
- private string? filterValue;
233
114
 
234
115
  private async Task LoadDataAsync()
235
116
  {
@@ -239,8 +120,7 @@ For production apps, combine paging, sorting, and filtering into a single server
239
120
  PageSize = pageSize,
240
121
  SortField = currentSort?.FirstOrDefault()?.FieldName,
241
122
  SortDirection = currentSort?.FirstOrDefault()?.Dir.ToString(),
242
- FilterField = filterField,
243
- FilterValue = filterValue
123
+ Filter = Translate(currentFilter)
244
124
  });
245
125
 
246
126
  data = result.Items;
@@ -250,50 +130,21 @@ For production apps, combine paging, sorting, and filtering into a single server
250
130
  }
251
131
  ```
252
132
 
253
- ---
254
-
255
- ## Virtualization
256
-
257
- ### How virtualization works
258
-
259
- Virtualization is **built-in and automatic**. The grid only renders DOM elements for the visible viewport. As the user scrolls, rows and cells are recycled.
260
-
261
- ### Requirements
262
-
263
- 1. **The grid must have a fixed `Height`** - set `Height="500px"` or `Height="80vh"`. Without a height, the grid renders all rows and virtualization is disabled.
264
- 2. **Column widths help column virtualization** - when total column width exceeds the grid width, columns outside the viewport are not rendered.
133
+ The grid still renders sort and filter UI while you own the actual data transformation. To stop it re-sorting or re-filtering the page it already has, assign noop sorting/filtering strategies on the grid — check `get_api_reference` for the current strategy types.
265
134
 
266
- ### Row virtualization
135
+ `IgbGridLite` handles remote operations differently, through `DataPipelineConfiguration` rather than events — see [`types.md`](./types.md).
267
136
 
268
- ```razor
269
- <IgbGrid Data="largeDataSet" PrimaryKey="Id"
270
- Width="100%" Height="600px" AutoGenerate="true" />
271
- ```
272
-
273
- Even with 100,000+ rows, only ~20-30 (depending on row height and grid height) are rendered at any time.
274
-
275
- ### Column virtualization
137
+ ## Virtualization
276
138
 
277
- ```razor
278
- <IgbGrid Data="wideData" PrimaryKey="Id" Width="800px" Height="600px">
279
- @for (int i = 0; i < 50; i++)
280
- {
281
- <IgbColumn Field="@($"Col{i}")" Header="@($"Column {i}")" Width="150px" />
282
- }
283
- </IgbGrid>
284
- ```
139
+ Row and column virtualization are automatic; the grid renders only the visible viewport and recycles rows as the user scrolls. Even at 100k+ rows only a few dozen exist in the DOM.
285
140
 
286
- With 50 columns at 150px each (7500px total) in an 800px wide grid, only the visible columns are rendered.
141
+ Two requirements:
287
142
 
288
- ---
143
+ 1. **A fixed `Height`** (`"600px"`, `"80vh"`, or `100%` inside a sized parent). Without it every row renders and virtualization is off — this is the single biggest grid performance factor.
144
+ 2. For column virtualization, total column width must exceed the grid width. It works without per-column widths (the grid falls back to a minimum column width), so do not add widths just for this.
289
145
 
290
- ## Key Rules
146
+ ## Rules
291
147
 
292
- 1. **`IgbPaginator` goes inside the grid** - it is a child component, not a sibling.
293
- 2. **Remote paging requires `TotalRecords`** - without it, the paginator cannot calculate page count.
294
- 3. **Handle events for remote operations** - `SortingDone`, `FilteringDone`, `PageChange` are your hooks to fetch server data.
295
- 4. **Virtualization needs a fixed `Height`** - this is the #1 performance requirement.
296
- 5. **Do not use `.Skip().Take()` on `IQueryable` directly on the grid** - the grid expects a materialized collection (`List<T>` or `T[]`). Fetch data asynchronously and set it as the `Data` property.
297
- 6. **`StateHasChanged()` after data updates** - call it after reassigning the `Data` property from an async operation.
298
- 7. **Remote operations override client-side** - when using remote sorting/filtering, the grid still shows sort/filter UI, but you handle the actual data transformation on the server.
299
- 8. **Paging is not available on IgbPivotGrid** - the Pivot Grid does not support pagination.
148
+ - `IgbPaginator` is a **child** of the grid, not a sibling.
149
+ - Always call `StateHasChanged()` after reassigning `Data` from an async operation.
150
+ - `Data` must be a materialized `List<T>` or `T[]` — do not hand the grid an `IQueryable` and expect it to compose `Skip`/`Take`.
@@ -1,278 +1,77 @@
1
- # Sizing - Grid Width, Height, Column Sizing & Cell Spacing
1
+ # Sizing — Grid Dimensions, Column Widths, Density
2
2
 
3
- > **Part of the [`igniteui-blazor-grids`](../SKILL.md) skill hub.**
4
- > For grid setup and column configuration — see [`structure.md`](./structure.md).
5
-
6
- ## Contents
7
-
8
- - [Grid Width](#grid-width)
9
- - [Grid Height](#grid-height)
10
- - [Column Sizing](#column-sizing)
11
- - [Row Height](#row-height)
12
- - [Cell Spacing (CSS Variables)](#cell-spacing-css-variables)
13
- - [Key Rules](#key-rules)
14
-
15
- ---
16
-
17
- ## Grid Width
18
-
19
- ### Pixel width
3
+ ## Grid width and height
20
4
 
21
5
  ```razor
22
- <IgbGrid Data="data" PrimaryKey="Id" Width="800px" Height="500px">
23
- ...
24
- </IgbGrid>
25
- ```
26
-
27
- ### Percentage width
28
-
29
- ```razor
30
- <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="500px">
31
- ...
32
- </IgbGrid>
33
- ```
34
-
35
- ### Default width
36
-
37
- When `Width` is not set, the grid defaults to `100%` of its parent container.
38
-
39
- ### Key behavior
40
-
41
- - If the total column width exceeds the grid width, a horizontal scrollbar appears and column virtualization activates.
42
- - If the total column width is less than the grid width, columns stretch to fill (unless explicit widths are set).
43
-
44
- ---
45
-
46
- ## Grid Height
47
-
48
- ### Pixel height
49
-
50
- ```razor
51
- <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="600px">
52
- ...
53
- </IgbGrid>
54
- ```
55
-
56
- ### Percentage height
6
+ <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="600px">…</IgbGrid>
57
7
 
58
- ```razor
59
- <!-- Parent must have a defined height for percentage to work -->
60
8
  <div style="height: 80vh;">
61
- <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="100%">
62
- ...
63
- </IgbGrid>
9
+ <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="100%">…</IgbGrid>
64
10
  </div>
65
11
  ```
66
12
 
67
- ### No height (null/unset)
13
+ `Width` defaults to `100%` of the parent. If the columns are wider than the grid a horizontal scrollbar appears and column virtualization activates; if they are narrower they stretch to fill.
68
14
 
69
- When `Height` is not set, the grid renders **all rows** without a vertical scrollbar. This disables row virtualization.
70
-
71
- ```razor
72
- <!-- No Height: renders all rows, no virtualization -->
73
- <IgbGrid Data="data" PrimaryKey="Id" Width="100%">
74
- ...
75
- </IgbGrid>
76
- ```
77
-
78
- > **Warning:** Without a height, large datasets will render all rows to the DOM, causing severe performance degradation. Always set `Height` for datasets with more than 50 rows.
79
-
80
- ### Auto height
81
-
82
- The grid does not have a built-in "auto height" mode. To fit a limited number of rows, calculate the height:
15
+ **`Height` has no default.** Unset, the grid renders every row with no vertical scrollbar and **row virtualization is disabled** — fine for a handful of rows, ruinous past ~50. There is no auto-height mode; to fit a bounded number of rows, compute it:
83
16
 
84
17
  ```razor
85
18
  @{
86
19
  var rowCount = Math.Min(data.Count, 20);
87
- var gridHeight = $"{50 + rowCount * 50}px"; // 50px header + 50px per row
20
+ var gridHeight = $"{50 + rowCount * 50}px"; // header + rows, at the default density
88
21
  }
89
-
90
- <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="@gridHeight">
91
- ...
92
- </IgbGrid>
22
+ <IgbGrid Data="data" PrimaryKey="Id" Width="100%" Height="@gridHeight">…</IgbGrid>
93
23
  ```
94
24
 
95
- ---
96
-
97
- ## Column Sizing
25
+ ## Column widths
98
26
 
99
- ### Fixed pixel width
27
+ **Default to no `Width` at all.** With none set, the grid distributes the available space proportionally (down to a ~136px minimum per column) and fills the container with no dead space on the right. Add widths only when the user asks for fixed sizing — and if you set a width on some columns, leave at least one without so it absorbs the remainder.
100
28
 
101
29
  ```razor
102
30
  <IgbColumn Field="Id" Header="ID" Width="80px" />
103
- <IgbColumn Field="Name" Header="Name" Width="250px" />
104
- <IgbColumn Field="Department" Header="Department" Width="200px" />
105
- ```
106
-
107
- ### Percentage width
108
-
109
- ```razor
110
- <IgbColumn Field="Id" Header="ID" Width="10%" />
111
- <IgbColumn Field="Name" Header="Name" Width="40%" />
112
- <IgbColumn Field="Department" Header="Department" Width="25%" />
113
- <IgbColumn Field="Salary" Header="Salary" Width="25%" />
114
- ```
115
-
116
- ### Auto-size (fit content)
117
-
118
- No explicit width - the column auto-sizes:
119
-
120
- ```razor
121
- <IgbColumn Field="Name" Header="Name" />
122
- ```
123
-
124
- Without a `Width`, the grid distributes available space proportionally among columns.
125
-
126
- ### Min/Max width constraints
127
-
128
- ```razor
129
31
  <IgbColumn Field="Name" Header="Name" Width="200px" MinWidth="100px" MaxWidth="400px" Resizable="true" />
32
+ <IgbColumn Field="Notes" Header="Notes" /> @* absorbs the rest *@
130
33
  ```
131
34
 
132
- - `MinWidth` prevents the column from shrinking below a threshold (useful with resizing).
133
- - `MaxWidth` prevents the column from growing beyond a threshold.
35
+ - `Width` accepts px, `%`, or `"auto"`. `"auto"` fits header and visible content **once at initial render** and does not track later data changes.
36
+ - `MinWidth` / `MaxWidth` bound user resizing — set both whenever `Resizable="true"`.
37
+ - Widths are border-box: padding and borders are included.
38
+ - `ColumnWidth` on the grid sets a default for all columns instead of repeating a per-column `Width`.
134
39
 
135
- ### Column resizing
136
-
137
- ```razor
138
- <IgbGrid Data="data" PrimaryKey="Id">
139
- <IgbColumn Field="Name" Header="Name" Width="200px" Resizable="true" />
140
- <IgbColumn Field="Department" Header="Department" Width="200px" Resizable="true" />
141
- <IgbColumn Field="Salary" Header="Salary" Width="150px" Resizable="true" />
142
- </IgbGrid>
143
- ```
144
-
145
- Users can drag column borders to resize. Combine with `MinWidth` and `MaxWidth` for constrained resizing.
146
-
147
- ### Auto-size column to fit content
148
-
149
- Programmatically auto-size a column to fit its longest visible cell value:
40
+ Auto-size from code:
150
41
 
151
42
  ```razor
152
43
  @code {
153
44
  private IgbGrid grid = default!;
154
45
 
155
- private void AutoSizeNameColumn()
156
- {
157
- var column = grid.GetColumnByName("Name");
158
- column.Autosize(false); // false = include cell content, true = header only
159
- }
160
-
161
- private void AutoSizeAllColumns()
162
- {
163
- foreach (var col in grid.Columns)
164
- {
165
- col.Autosize(false);
166
- }
167
- }
46
+ private void AutoSizeName() => grid.GetColumnByName("Name").Autosize(false); // false = include cell content
47
+ private void AutoSizeAll() { foreach (var col in grid.Columns) col.Autosize(false); }
168
48
  }
169
49
  ```
170
50
 
171
- ### Column auto-width on init
51
+ ## Row height and density
172
52
 
173
- ```razor
174
- <IgbColumn Field="Name" Header="Name" Width="auto" />
175
- ```
53
+ Row height, cell padding, and header height all follow the `--ig-size` CSS custom property. All rows in a grid share one height — variable row heights are not supported.
176
54
 
177
- When `Width="auto"`, the column width adjusts on initial render to fit the header and visible content.
178
-
179
- ---
180
-
181
- ## Row Height
182
-
183
- ### Default row height
184
-
185
- The default row height depends on the `--ig-size` CSS custom property. Set it on the grid or a parent element:
186
-
187
- ```css
188
- igc-grid {
189
- --ig-size: var(--ig-size-large); /* default */
190
- }
191
- ```
192
-
193
- | `--ig-size` value | Approximate Row Height |
55
+ | `--ig-size` | Row height |
194
56
  |---|---|
195
- | `var(--ig-size-large)` | 50px (default) |
196
- | `var(--ig-size-medium)` | 40px |
197
- | `var(--ig-size-small)` | 32px |
198
-
199
- ### Custom row height
200
-
201
- Use CSS to override row height:
202
-
203
- ```css
204
- igc-grid::part(tbody-content) igc-grid-row {
205
- height: 60px;
206
- }
207
- ```
208
-
209
- Or use `RowHeight` parameter:
57
+ | `var(--ig-size-large)` | ~50px (default) |
58
+ | `var(--ig-size-medium)` | ~40px |
59
+ | `var(--ig-size-small)` | ~32px |
210
60
 
211
61
  ```razor
212
- <IgbGrid Data="data" PrimaryKey="Id" RowHeight="60">
213
- ...
214
- </IgbGrid>
62
+ <IgbGrid Data="data" PrimaryKey="Id" class="compact-grid">…</IgbGrid>
215
63
  ```
216
64
 
217
- ---
218
-
219
- ## Cell Spacing (CSS Variables)
220
-
221
- The grid does not expose individual cell-padding CSS custom properties. Cell padding and row height are controlled by the `--ig-size` CSS variable:
222
-
223
- | CSS Variable | Description | Default |
224
- |---|---|---|
225
- | `--ig-size` | Overall component size (affects row height, cell padding, header height) | `var(--ig-size-large)` |
226
-
227
- ### Sizing via `--ig-size`
228
-
229
- The grid respects the global `--ig-size` CSS variable for responsive sizing:
230
-
231
65
  ```css
232
- /* Compact grid */
233
- igc-grid {
234
- --ig-size: var(--ig-size-small);
235
- }
236
-
237
- /* Medium grid */
238
- igc-grid {
239
- --ig-size: var(--ig-size-medium);
240
- }
241
-
242
- /* Large grid (default) */
243
- igc-grid {
244
- --ig-size: var(--ig-size-large);
245
- }
66
+ /* global CSS */
67
+ .compact-grid { --ig-size: var(--ig-size-small); }
68
+ igc-grid { --ig-size: var(--ig-size-medium); }
246
69
  ```
247
70
 
248
- ### Scoped sizing
71
+ In a `.razor.css` isolation file prefix the `igc-*` selector with `::deep`. The grid exposes no separate cell-padding custom property; `--ig-size` is the single density knob.
249
72
 
250
- Apply different sizing to a specific grid:
73
+ An explicit override wins over the density scale:
251
74
 
252
75
  ```razor
253
- <IgbGrid Data="data" PrimaryKey="Id" class="compact-grid">
254
- ...
255
- </IgbGrid>
256
-
257
- <style>
258
- .compact-grid {
259
- --ig-size: var(--ig-size-small);
260
- }
261
- </style>
76
+ <IgbGrid Data="data" PrimaryKey="Id" RowHeight="60">…</IgbGrid>
262
77
  ```
263
-
264
- ---
265
-
266
- ## Key Rules
267
-
268
- 1. **Do not add column `Width` unless explicitly requested** — omitting `Width` causes the grid to distribute available space proportionally across all columns, producing a responsive layout with no empty space. Only set explicit pixel or percentage widths when the user specifically asks for fixed column sizing.
269
- 2. **If any column has a specified `Width`, leave at least one column without `Width`** - so it fills the remaining space in the grid.
270
- 3. **Always set `Height` for performance** - without it, virtualization is disabled and all rows render to the DOM.
271
- 4. **Percentage height needs a sized parent** - `Height="100%"` only works if the parent element has an explicit height.
272
- 5. **Box model is border-box** - column widths include padding and borders.
273
- 6. **Horizontal scroll triggers when columns overflow** - if total column width > grid width, a horizontal scrollbar appears.
274
- 7. **`MinWidth` and `MaxWidth` constrain resizing** - always set them when `Resizable="true"` for predictable UX.
275
- 8. **`--ig-size` controls the overall density** - it affects row height, cell padding, header height, and internal spacing.
276
- 9. **Column virtualization works without explicit per-column widths** — when no `Width` is set on a column, the grid distributes available space across all columns (minimum 136px per column). If columns cannot fit at that minimum, a horizontal scrollbar appears and horizontal virtualization activates automatically. You can also set a grid-level default with `ColumnWidth` on `IgbGrid` instead of setting per-column widths. Only set per-column `Width` when a specific column needs a fixed or percentage size.
277
- 10. **Auto-size is a one-time operation** - `Width="auto"` on a column fits content at initial render; it doesn't update dynamically as data changes.
278
- 11. **Row height consistency** - all rows in a grid have the same height. Variable row height is not supported.