igniteui-cli 15.5.1 → 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.
- package/package.json +4 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/AGENTS.md +6 -3
- package/templates/blazor/igb/projects/ai-config/files/skills/README.md +30 -45
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/SKILL.md +48 -96
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/charts.md +61 -238
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/data-display.md +60 -193
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/feedback.md +36 -92
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +66 -224
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout-manager.md +39 -88
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/layout.md +75 -152
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +40 -149
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/SKILL.md +58 -243
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +89 -280
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +143 -431
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/SKILL.md +91 -157
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/data-operations.md +50 -228
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +61 -222
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/features.md +67 -360
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/grid-migration.md +55 -236
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/paging-remote.md +53 -202
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/sizing.md +31 -232
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/state.md +27 -119
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/structure.md +88 -363
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/types.md +87 -415
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/SKILL.md +8 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-lite-testing/references/interop-contracts.md +42 -6
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/SKILL.md +83 -211
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/common-patterns.md +93 -184
- package/templates/react/igr-ts/projects/ai-config/files/skills/README.md +30 -83
- package/templates/react/igr-ts/projects/ai-config/files/skills/grid-lite-to-igr-grid-migration/SKILL.md +98 -191
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/SKILL.md +38 -147
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENTS.md +65 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/DATAVIZ.md +90 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP.md +43 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/TROUBLESHOOTING.md +17 -145
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/USAGE.md +85 -0
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/SKILL.md +83 -135
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/CSS-THEMING.md +51 -218
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/SKILL.md +58 -187
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-generate-from-image-design/reference/gotchas.md +55 -154
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-optimize-bundle-size/SKILL.md +48 -401
- package/templates/webcomponents/igc-ts/constants.d.ts +5 -5
- package/templates/webcomponents/igc-ts/constants.js +5 -5
- package/templates/webcomponents/igc-ts/projects/_base/files/package.json +1 -1
- package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +6 -6
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/mcp-setup.md +0 -78
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/mcp-setup.md +0 -78
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-theming/references/mcp-setup.md +0 -81
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/CHARTS-GRIDS.md +0 -398
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/COMPONENT-CATALOGUE.md +0 -161
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/EVENT-HANDLING.md +0 -72
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/INSTALLATION.md +0 -139
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/JSX-PATTERNS.md +0 -187
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/MCP-SERVER.md +0 -77
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-components/reference/REFS-FORMS.md +0 -232
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/MCP-SERVER.md +0 -67
- package/templates/react/igr-ts/projects/ai-config/files/skills/igniteui-react-customize-theme/reference/TROUBLESHOOTING.md +0 -35
- 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
|
-
|
|
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"
|
|
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
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
33
|
+
## Remote paging
|
|
86
34
|
|
|
87
|
-
|
|
35
|
+
Bind `Data` to just the current page and tell the paginator the true total.
|
|
88
36
|
|
|
89
37
|
```razor
|
|
90
|
-
<IgbGrid
|
|
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
|
-
<
|
|
95
|
-
|
|
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
|
|
46
|
+
private int totalRecords, currentPage;
|
|
105
47
|
private int pageSize = 20;
|
|
106
|
-
private int currentPage = 0;
|
|
107
48
|
|
|
108
|
-
protected override
|
|
109
|
-
{
|
|
110
|
-
await LoadPageAsync();
|
|
111
|
-
}
|
|
49
|
+
protected override Task OnInitializedAsync() => LoadPageAsync();
|
|
112
50
|
|
|
113
|
-
private
|
|
51
|
+
private Task OnPageChange(IgbNumberEventArgs args)
|
|
114
52
|
{
|
|
115
53
|
currentPage = (int)args.Detail;
|
|
116
|
-
|
|
54
|
+
return LoadPageAsync();
|
|
117
55
|
}
|
|
118
56
|
|
|
119
|
-
private
|
|
57
|
+
private Task OnPerPageChange(IgbNumberEventArgs args)
|
|
120
58
|
{
|
|
121
59
|
pageSize = (int)args.Detail;
|
|
122
60
|
currentPage = 0;
|
|
123
|
-
|
|
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
|
-
|
|
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
|
|
76
|
+
## Remote sorting and filtering
|
|
145
77
|
|
|
146
|
-
|
|
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
|
|
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
|
|
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
|
|
95
|
+
private Task OnSortingDone(IgbSortingExpressionEventArgs args)
|
|
169
96
|
{
|
|
170
97
|
currentSort = args.Detail;
|
|
171
98
|
currentPage = 0;
|
|
172
|
-
|
|
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
|
|
102
|
+
private Task OnFilteringDone(IgbFilteringExpressionsTreeEventArgs args)
|
|
182
103
|
{
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
|
109
|
+
private Task OnPageChange(IgbNumberEventArgs args)
|
|
211
110
|
{
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
|
|
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
|
-
|
|
135
|
+
`IgbGridLite` handles remote operations differently, through `DataPipelineConfiguration` rather than events — see [`types.md`](./types.md).
|
|
267
136
|
|
|
268
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
146
|
+
## Rules
|
|
291
147
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
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
|
|
1
|
+
# Sizing — Grid Dimensions, Column Widths, Density
|
|
2
2
|
|
|
3
|
-
|
|
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="
|
|
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
|
-
|
|
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
|
-
|
|
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";
|
|
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
|
-
|
|
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
|
-
- `
|
|
133
|
-
- `MaxWidth`
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
51
|
+
## Row height and density
|
|
172
52
|
|
|
173
|
-
|
|
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
|
-
|
|
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"
|
|
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
|
-
/*
|
|
233
|
-
|
|
234
|
-
|
|
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
|
-
|
|
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
|
-
|
|
73
|
+
An explicit override wins over the density scale:
|
|
251
74
|
|
|
252
75
|
```razor
|
|
253
|
-
<IgbGrid Data="data" PrimaryKey="Id"
|
|
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.
|