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,180 +1,132 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Gotchas — Mistakes That Compile But Look Wrong
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
- [CSS Isolation & Scoping](#css-isolation--scoping)
|
|
5
|
-
- [Chart Properties](#chart-properties)
|
|
6
|
-
- [Component Properties](#component-properties)
|
|
7
|
-
- [Theming Pitfalls](#theming-pitfalls)
|
|
8
|
-
- [Map Component](#map-component)
|
|
9
|
-
- [Dark Theme Specifics](#dark-theme-specifics)
|
|
10
|
-
- [Blazor-specific Gotchas](#blazor-specific-gotchas)
|
|
3
|
+
Check every entry against your component list before writing code. Chart, CSS, and Razor entries apply broadly, not only to the components they name.
|
|
11
4
|
|
|
12
|
-
|
|
5
|
+
## Razor & Blazor
|
|
13
6
|
|
|
14
|
-
|
|
7
|
+
### RZ9986 — dynamic `class` on an Ignite UI component
|
|
15
8
|
|
|
16
|
-
|
|
9
|
+
Mixing literal text with `@(...)` in one attribute on a component fails the build with *"Component attributes do not support complex content"*. Make the whole value a single C# expression.
|
|
17
10
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
| `::part()` | Target a named shadow DOM part directly | **Secondary** - only when no token covers it; confirm part names via `get_doc` |
|
|
22
|
-
| `::deep` | Pierce Blazor CSS isolation in `.razor.css` files | **File helper** - add it in `.razor.css`; never needed in global CSS |
|
|
11
|
+
```razor
|
|
12
|
+
@* ❌ RZ9986 *@
|
|
13
|
+
<IgbChip class="chip @(item == _selected ? "chip-active" : "")" />
|
|
23
14
|
|
|
24
|
-
|
|
15
|
+
@* ✅ *@
|
|
16
|
+
<IgbChip class="@ChipClass(item)" />
|
|
25
17
|
|
|
26
|
-
|
|
18
|
+
@code { string ChipClass(Item i) => i == _selected ? "chip chip-active" : "chip"; }
|
|
19
|
+
```
|
|
27
20
|
|
|
28
|
-
|
|
21
|
+
### CS1012 — single quotes in an inline lambda
|
|
29
22
|
|
|
30
|
-
|
|
31
|
-
- **DO NOT** use `::deep` for plain HTML class selectors. These are already scoped by Blazor's CSS isolation and work without `::deep`.
|
|
32
|
-
- **DO NOT** use `::deep` to target the root element of a component - Blazor places the scope attribute on the root element itself, so there is no scoped parent above it to make `::deep` work. Style the root element with a plain class selector.
|
|
23
|
+
`@onclick="() => Navigate('/dashboard')"` fails: the single quotes are parsed as a C# `char` literal. Use a named handler.
|
|
33
24
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
25
|
+
```razor
|
|
26
|
+
@* ❌ *@ <IgbNavDrawerItem @onclick="() => Navigate('/dashboard')">
|
|
27
|
+
@* ✅ *@ <IgbNavDrawerItem @onclick="NavigateToDashboard">
|
|
28
|
+
|
|
29
|
+
@code { void NavigateToDashboard() => NavigationManager.NavigateTo("/dashboard"); }
|
|
38
30
|
```
|
|
39
31
|
|
|
40
|
-
|
|
41
|
-
```css
|
|
42
|
-
::deep igc-chip { --ig-chip-background: var(--ig-primary-500); }
|
|
43
|
-
::deep igc-dialog::part(footer) { border-top: 1px solid var(--ig-gray-200); }
|
|
32
|
+
### BL0005 — setting parameters through `@ref`
|
|
44
33
|
|
|
45
|
-
.
|
|
46
|
-
```
|
|
34
|
+
Assigning component parameters from `OnAfterRenderAsync` (`chart.Brushes = "…"`) raises *"Component parameter should not be set outside of its component"*. Pass them as inline markup attributes instead.
|
|
47
35
|
|
|
48
|
-
|
|
36
|
+
### Async vs sync methods
|
|
49
37
|
|
|
50
|
-
|
|
38
|
+
Every component method has an `XAsync()` form and a sync twin `X()`. **Use `Async`.** The sync twin requires `IJSInProcessRuntime` and throws `InvalidOperationException` on Blazor Server; it only works in WebAssembly and MAUI WebView.
|
|
51
39
|
|
|
52
|
-
|
|
40
|
+
### Other basics
|
|
53
41
|
|
|
54
|
-
|
|
42
|
+
- Parameters are PascalCase (`ChartType`, `DataSource`) — never Angular's `[chartType]`.
|
|
43
|
+
- Templates are Blazor render fragments with a cast `context`, not `<ng-template>`. On a grid column the cell template is `BodyTemplate`:
|
|
44
|
+
```razor
|
|
45
|
+
<IgbColumn Field="Name" Header="Name">
|
|
46
|
+
<BodyTemplate>
|
|
47
|
+
@{ var cell = (IgbCellTemplateContext)context; }
|
|
48
|
+
<strong>@cell.Cell.Value</strong>
|
|
49
|
+
</BodyTemplate>
|
|
50
|
+
</IgbColumn>
|
|
51
|
+
```
|
|
52
|
+
- `@bind-Value` / `@bind-Checked` — verify the bindable parameter exists rather than inventing one.
|
|
53
|
+
- Mock data is C# `record` or `class`, not a TypeScript interface.
|
|
54
|
+
- `AddIgniteUIBlazor()` must be called in `Program.cs`. Listing `typeof(Igb…Module)` values pre-loads those modules; in `IgniteUI.Blazor.Lite` components also self-register on first render.
|
|
55
55
|
|
|
56
|
-
|
|
57
|
-
Category charts show markers at every data point by default. If the screenshot does not show markers, set `MarkerTypes` using the documented pattern for the installed version. When setting it from code, add the enum value after the chart reference is ready:
|
|
58
|
-
```razor
|
|
59
|
-
<IgbCategoryChart @ref="chart" ... />
|
|
60
|
-
|
|
61
|
-
@code {
|
|
62
|
-
private IgbCategoryChart chart = default!;
|
|
63
|
-
|
|
64
|
-
protected override void OnAfterRender(bool firstRender)
|
|
65
|
-
{
|
|
66
|
-
if (firstRender)
|
|
67
|
-
{
|
|
68
|
-
chart.MarkerTypes.Add(MarkerType.None);
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
}
|
|
72
|
-
```
|
|
56
|
+
## CSS scoping
|
|
73
57
|
|
|
74
|
-
|
|
75
|
-
Charts, maps, gauges, and sparklines ignore the global CSS custom property theme. Set their visual properties explicitly via component parameters:
|
|
76
|
-
```razor
|
|
77
|
-
<IgbCategoryChart
|
|
78
|
-
Brushes="#4FC3F7 #81C784 #FFB74D"
|
|
79
|
-
Outlines="#4FC3F7 #81C784 #FFB74D"
|
|
80
|
-
MarkerBrushes="#4FC3F7 #81C784 #FFB74D"
|
|
81
|
-
MarkerOutlines="#4FC3F7 #81C784 #FFB74D"
|
|
82
|
-
XAxisLabelTextColor="#666666"
|
|
83
|
-
YAxisLabelTextColor="#666666" />
|
|
84
|
-
```
|
|
58
|
+
Full rules are in the theming skill's [`common-patterns.md`](../../igniteui-blazor-theming/references/common-patterns.md). The short version:
|
|
85
59
|
|
|
86
|
-
|
|
60
|
+
| Mechanism | When |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `--ig-*` design tokens | **primary** — whenever a token exists for the property |
|
|
63
|
+
| `::part(name)` | only when no token covers it, and only after confirming the part name |
|
|
64
|
+
| `::deep` | only in `.razor.css`, only on `igc-*` selectors |
|
|
87
65
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
66
|
+
```css
|
|
67
|
+
/* app.css — global, no ::deep */
|
|
68
|
+
igc-chip { --ig-chip-background: var(--ig-primary-500); }
|
|
69
|
+
igc-dialog::part(footer) { border-top: 1px solid var(--ig-gray-200); }
|
|
70
|
+
|
|
71
|
+
/* MyView.razor.css — ::deep on igc-*, never on your own class selectors */
|
|
72
|
+
::deep igc-chip { --ig-chip-background: var(--ig-primary-500); }
|
|
73
|
+
.dashboard-shell { display: grid; grid-template-columns: 260px 1fr; }
|
|
92
74
|
```
|
|
93
75
|
|
|
94
|
-
|
|
95
|
-
It does **NOT** exist on `IgbSparkline`. For sparkline fill, use the `Brush` parameter.
|
|
76
|
+
`::deep` does **not** work on the component's own root element — Blazor puts the scope attribute there, so there is no scoped parent above it. Never add `::deep` to a `:root {}` block. `create_component_theme` emits global CSS; use it verbatim in `app.css`. Blazor projects have no Sass step.
|
|
96
77
|
|
|
97
|
-
|
|
98
|
-
`IgbSparkline` supports only `Line`, `Area`, `Column`, and `WinLoss` display types. `Area` renders as angular polygon fills, not smooth curves. If the design shows smooth mountain-shaped area sparklines, use a small `IgbCategoryChart` with `ChartType="CategoryChartType.SplineArea"`:
|
|
78
|
+
## Charts
|
|
99
79
|
|
|
100
|
-
|
|
101
|
-
<!-- ❌ Angular fill - no smooth curves available on IgbSparkline -->
|
|
102
|
-
<IgbSparkline DisplayType="SparklineDisplayType.Area" Brush="#5B57E8" ... />
|
|
103
|
-
|
|
104
|
-
<!-- ✅ Smooth spline area sparkline -->
|
|
105
|
-
<IgbCategoryChart @ref="splineChart"
|
|
106
|
-
ChartType="@CategoryChartType.SplineArea"
|
|
107
|
-
Brushes="#5B57E8"
|
|
108
|
-
Outlines="#5B57E8"
|
|
109
|
-
AreaFillOpacity="0.35"
|
|
110
|
-
XAxisLabelTextColor="transparent"
|
|
111
|
-
YAxisLabelTextColor="transparent"
|
|
112
|
-
Height="70px"
|
|
113
|
-
Width="100%"
|
|
114
|
-
DataSource="@SparkData" />
|
|
115
|
-
```
|
|
80
|
+
### They ignore the CSS theme entirely
|
|
116
81
|
|
|
82
|
+
Charts, maps, gauges, and sparklines do not read `--ig-*` custom properties. Set colors through parameters, using resolved values rather than `var()` references:
|
|
117
83
|
|
|
118
|
-
### `IncludedProperties` and `ExcludedProperties` are string arrays
|
|
119
|
-
Pass them as bound parameters:
|
|
120
84
|
```razor
|
|
121
|
-
<IgbCategoryChart
|
|
85
|
+
<IgbCategoryChart Brushes="#4FC3F7 #81C784" Outlines="#4FC3F7 #81C784"
|
|
86
|
+
MarkerBrushes="#4FC3F7 #81C784"
|
|
87
|
+
XAxisLabelTextColor="#666666" YAxisMajorStroke="#EEEEEE" />
|
|
122
88
|
```
|
|
123
89
|
|
|
124
|
-
|
|
90
|
+
`Brushes`, `Outlines`, `MarkerBrushes`, `MarkerOutlines` are **space-separated strings**, not arrays.
|
|
125
91
|
|
|
126
|
-
|
|
92
|
+
### Curve type is the most visible fidelity mistake
|
|
127
93
|
|
|
128
|
-
|
|
129
|
-
System.InvalidOperationException: IgbRingSeries does not have a property matching 'InnerExtent'
|
|
130
|
-
```
|
|
94
|
+
Match `ChartType` to the shape in the image: smooth flowing → `Spline` / `SplineArea`; angular → `Line` / `Area`; stepped → `StepLine` / `StepArea`. Do not default to `Line` when the image shows curves.
|
|
131
95
|
|
|
132
|
-
|
|
133
|
-
```razor
|
|
134
|
-
<!-- ✅ InnerExtent on the chart -->
|
|
135
|
-
<IgbDoughnutChart InnerExtent="0.45" Width="220px" Height="220px">
|
|
136
|
-
<IgbRingSeries ValueMemberPath="Value" LabelMemberPath="Label" ... />
|
|
137
|
-
</IgbDoughnutChart>
|
|
96
|
+
### Markers appear at every point by default
|
|
138
97
|
|
|
139
|
-
|
|
140
|
-
|
|
98
|
+
If the image has no dots on the line, add `MarkerType.None` to `MarkerTypes` once the chart reference is ready.
|
|
99
|
+
|
|
100
|
+
### `IncludedProperties` / `ExcludedProperties` are `string[]`
|
|
101
|
+
|
|
102
|
+
```razor
|
|
103
|
+
<IgbCategoryChart IncludedProperties='@(new string[] { "Month", "Revenue" })' />
|
|
141
104
|
```
|
|
142
105
|
|
|
143
|
-
|
|
106
|
+
A plain string is a type mismatch. `XAxisLabel` formats labels — it does not select a data field.
|
|
144
107
|
|
|
145
|
-
|
|
108
|
+
### `InnerExtent` is a chart property, never a series property
|
|
146
109
|
|
|
147
110
|
```razor
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
<!-- ❌ BL0005 warning -->
|
|
152
|
-
jobSeries.Brushes = "#CF6E7A #6C74DC #D4A84B";
|
|
111
|
+
@* ✅ *@ <IgbDoughnutChart InnerExtent="0.45"><IgbRingSeries … /></IgbDoughnutChart>
|
|
112
|
+
@* ❌ runtime crash: IgbRingSeries does not have a property matching 'InnerExtent' *@
|
|
113
|
+
<IgbRingSeries InnerExtent="0.45" />
|
|
153
114
|
```
|
|
154
115
|
|
|
155
|
-
###
|
|
156
|
-
Match `ChartType` to the curve shape in the screenshot:
|
|
157
|
-
- Smooth flowing curves → `Spline` (lines) or `SplineArea` (filled)
|
|
158
|
-
- Angular/jagged lines → `Line` or `Area`
|
|
159
|
-
- Step-shaped → `StepLine` or `StepArea`
|
|
116
|
+
### Choosing the right circular component
|
|
160
117
|
|
|
161
|
-
|
|
118
|
+
- Thick static ring, centered label, no needle → `IgbDoughnutChart` + `IgbRingSeries`, label absolutely positioned over it.
|
|
119
|
+
- Thin animated spinner → `IgbCircularProgress` (not a visualization).
|
|
120
|
+
- Needle on a scale arc → `IgbRadialGauge`.
|
|
162
121
|
|
|
163
|
-
|
|
164
|
-
- **Thick static ring with a centred label and no needle** → `IgbDoughnutChart` + `IgbRingSeries`. Place `InnerExtent` on the chart, not the series. Overlay the label with `position: absolute` inside a `position: relative` wrapper.
|
|
165
|
-
- **Thin animated spinner / loading progress** → `IgbCircularProgress`. Not a data visualisation.
|
|
166
|
-
- **Needle pointer on a scale arc** → `IgbRadialGauge`.
|
|
167
|
-
|
|
168
|
-
`IgbRadialGauge` and `IgbCircularProgress` will never produce a clean static ring. Use `IgbDoughnutChart` whenever the design shows a coloured arc ring with a centred value and no needle.
|
|
122
|
+
Neither gauge nor progress will produce a clean static ring.
|
|
169
123
|
|
|
170
124
|
```razor
|
|
171
125
|
<div class="gauge-wrapper">
|
|
172
126
|
<IgbDoughnutChart InnerExtent="0.62" Height="160px" Width="160px" AllowSliceExplosion="false">
|
|
173
|
-
<IgbRingSeries ValueMemberPath="Value" LabelMemberPath="Category"
|
|
174
|
-
LabelsPosition="
|
|
175
|
-
|
|
176
|
-
Brushes="#5B57E8 #e8e8f5"
|
|
177
|
-
Outlines="transparent transparent"
|
|
127
|
+
<IgbRingSeries DataSource="@GaugeData" ValueMemberPath="Value" LabelMemberPath="Category"
|
|
128
|
+
LabelsPosition="LabelsPosition.None"
|
|
129
|
+
Brushes="#5B57E8 #E8E8F5" Outlines="transparent transparent"
|
|
178
130
|
RadiusFactor="0.95" />
|
|
179
131
|
</IgbDoughnutChart>
|
|
180
132
|
<div class="gauge-label">75%</div>
|
|
@@ -186,357 +138,117 @@ Do not default to `Line` or `Area` when the screenshot shows smooth curves. The
|
|
|
186
138
|
.gauge-label { position: absolute; font-size: 1.9rem; font-weight: 700; }
|
|
187
139
|
```
|
|
188
140
|
|
|
189
|
-
###
|
|
190
|
-
Charts may render with zero height inside a CSS Grid container. Set `min-height: 0` on the grid cell and `Height="100%"` on the chart component so the chart fills its container without requiring a fixed pixel value:
|
|
191
|
-
```css
|
|
192
|
-
.chart-container {
|
|
193
|
-
min-height: 0; /* Prevents the CSS Grid track from collapsing */
|
|
194
|
-
}
|
|
195
|
-
```
|
|
196
|
-
```razor
|
|
197
|
-
<IgbCategoryChart Height="100%" Width="100%" ... />
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
---
|
|
201
|
-
|
|
202
|
-
## Component Properties
|
|
203
|
-
|
|
204
|
-
### IgbAvatar: use `Shape` parameter
|
|
205
|
-
Use the `Shape` parameter with `AvatarShape.Circle`, `AvatarShape.Rounded`, or `AvatarShape.Square`. There is no `RoundShape` property:
|
|
206
|
-
```razor
|
|
207
|
-
<IgbAvatar Shape="AvatarShape.Circle" Initials="JD" />
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### Icons in web component slots: use IgbIcon, not font-icon spans
|
|
141
|
+
### `IgbSparkline` has no smooth area
|
|
211
142
|
|
|
212
|
-
|
|
143
|
+
It supports only `Line`, `Area`, `Column`, `WinLoss`, and `Area` fills with angular polygons. For a smooth mountain-shaped micro-chart use a small `IgbCategoryChart` with `ChartType="CategoryChartType.SplineArea"` and `AreaFillOpacity` — `AreaFillOpacity` does not exist on `IgbSparkline`.
|
|
213
144
|
|
|
214
|
-
|
|
215
|
-
<!-- ❌ icon drifts to top -->
|
|
216
|
-
<IgbInput><span slot="prefix" class="material-icons">search</span></IgbInput>
|
|
145
|
+
### Charts collapse to zero height inside CSS Grid
|
|
217
146
|
|
|
218
|
-
|
|
219
|
-
|
|
147
|
+
```css
|
|
148
|
+
.chart-container { min-height: 0; } /* stops the grid track collapsing */
|
|
220
149
|
```
|
|
221
|
-
Register the icon in `OnAfterRenderAsync(firstRender)` after `EnsureReady()`.
|
|
222
|
-
|
|
223
|
-
### IgbList: slot-based structure
|
|
224
|
-
Use named `slot` attributes on child elements inside `IgbListItem` for positioning:
|
|
225
150
|
```razor
|
|
226
|
-
<
|
|
227
|
-
<IgbAvatar slot="start" Shape="AvatarShape.Circle" Initials="AB" />
|
|
228
|
-
<span slot="title">Item Title</span>
|
|
229
|
-
<span slot="subtitle">Secondary text</span>
|
|
230
|
-
<IgbIcon slot="end" Collection="material" IconName="chevron_right" />
|
|
231
|
-
</IgbListItem>
|
|
151
|
+
<IgbCategoryChart Height="100%" Width="100%" />
|
|
232
152
|
```
|
|
233
153
|
|
|
234
|
-
|
|
235
|
-
The component's `::part(base)` is always `position: fixed; transform: translateX(-Npx)` - the host contributes `width: 0` to the layout. `Open="true"` makes it visible but still floating over content. `slot="mini"` adds a collapsed icon-only state. There is no `pin`/`pinned` Blazor parameter.
|
|
154
|
+
Charts never auto-size — always set `Width` and `Height`.
|
|
236
155
|
|
|
237
|
-
|
|
156
|
+
### Map series are declared, not added from code
|
|
238
157
|
|
|
239
|
-
### IgbTileManager: drag and resize modes
|
|
240
|
-
Set `DragMode` and `ResizeMode` for interactive dashboards:
|
|
241
158
|
```razor
|
|
242
|
-
<
|
|
243
|
-
<
|
|
244
|
-
|
|
159
|
+
<IgbGeographicMap Height="500px" Width="100%">
|
|
160
|
+
<IgbGeographicSymbolSeries DataSource="Locations"
|
|
161
|
+
LatitudeMemberPath="Lat" LongitudeMemberPath="Lon"
|
|
162
|
+
MarkerType="MarkerType.Circle" MarkerBrush="#FF5722" />
|
|
163
|
+
</IgbGeographicMap>
|
|
245
164
|
```
|
|
246
165
|
|
|
247
|
-
|
|
166
|
+
OpenStreetMap tiles are light. For a dark design, filter the container: `filter: grayscale(0.8) brightness(0.6);` — tune to match the image.
|
|
248
167
|
|
|
249
|
-
|
|
250
|
-
The grid requires a container with a defined height. Without it, the grid will not virtualize and may render all rows:
|
|
251
|
-
```css
|
|
252
|
-
::deep igc-grid {
|
|
253
|
-
height: 500px;
|
|
254
|
-
}
|
|
255
|
-
```
|
|
168
|
+
## Components
|
|
256
169
|
|
|
257
|
-
|
|
170
|
+
### `IgbNavDrawer` — use `Position="Relative"` for a pinned sidebar
|
|
258
171
|
|
|
259
|
-
|
|
172
|
+
With `Start`/`End`/`Top`/`Bottom` the panel is `position: fixed`, floats over the content behind a dimming overlay, and the host contributes `width: 0` to the layout. There is no `Pin` parameter — but **`NavDrawerPosition.Relative` is the built-in pinned mode**: the panel becomes in-flow, the overlay is hidden, and closing slides it out by a negative margin.
|
|
260
173
|
|
|
261
|
-
### DV components do NOT inherit CSS theme colors
|
|
262
|
-
Charts, maps, gauges, and sparklines ignore the global CSS custom property theme entirely. Set their visual properties explicitly via component parameters. After a palette exists, use the resolved color values (not `var()` references) for DV component parameters:
|
|
263
174
|
```razor
|
|
264
|
-
<
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
YAxisMajorStroke="@grayLightColor" />
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
### Component-scoped theme overrides
|
|
272
|
-
For core UI component theming, use `create_component_theme` with `platform: "blazor"` and `output: "css"`. The MCP generates global CSS selectors (`igc-*`). Place the output in:
|
|
273
|
-
|
|
274
|
-
- **Global `app.css`** - use as-is (no `::deep`).
|
|
275
|
-
- **`.razor.css` isolation file** - add `::deep` to each selector:
|
|
276
|
-
|
|
277
|
-
```css
|
|
278
|
-
/* Dashboard.razor.css - add ::deep for isolation file */
|
|
279
|
-
::deep igc-grid {
|
|
280
|
-
--ig-grid-header-background: var(--ig-primary-100);
|
|
281
|
-
--ig-grid-content-background: var(--ig-surface-500);
|
|
282
|
-
}
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
Use `::part()` on an `igc-*` selector only when the property you need is not covered by any design token (verify via `get_component_design_tokens` first). In isolation files, combine `::deep` with `::part()`:
|
|
286
|
-
|
|
287
|
-
```css
|
|
288
|
-
/* MyView.razor.css */
|
|
289
|
-
::deep igc-dialog::part(footer) {
|
|
290
|
-
border-top: 1px solid var(--ig-gray-200);
|
|
291
|
-
}
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
### Nav drawer sizing
|
|
295
|
-
Size the drawer with layout CSS around the drawer or with CSS parts/tokens verified from the current docs.
|
|
296
|
-
```css
|
|
297
|
-
.shell {
|
|
298
|
-
display: grid;
|
|
299
|
-
grid-template-columns: 260px 1fr;
|
|
300
|
-
}
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
### Dark theme overrides for grids
|
|
304
|
-
In dark themes, grid headers and rows may need explicit background overrides to match the design's surface hierarchy:
|
|
305
|
-
```css
|
|
306
|
-
::deep igc-grid {
|
|
307
|
-
--ig-grid-header-background: var(--ig-surface-500);
|
|
308
|
-
--ig-grid-content-background: var(--ig-surface-500);
|
|
309
|
-
--ig-grid-row-hover-background: var(--ig-gray-100);
|
|
310
|
-
}
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
### No hardcoded colors after palette generation
|
|
314
|
-
Once a palette has been defined (via CSS custom property overrides or MCP `create_palette` / `create_theme`), core UI component colors should come from generated palette tokens - do not hardcode hex/RGB/HSL values. DV component parameters are the exception: charts, maps, gauges, and sparklines often need resolved color strings because they do not consume CSS variables consistently.
|
|
315
|
-
|
|
316
|
-
**WRONG** (hardcoded hex - breaks theme switching, ignores the palette):
|
|
317
|
-
```css
|
|
318
|
-
/* app.css - global */
|
|
319
|
-
igc-avatar {
|
|
320
|
-
--ig-avatar-background: #e91e63;
|
|
321
|
-
}
|
|
175
|
+
<div class="app-shell">
|
|
176
|
+
<IgbNavDrawer Open="true" Position="NavDrawerPosition.Relative">…</IgbNavDrawer>
|
|
177
|
+
<main>@Body</main>
|
|
178
|
+
</div>
|
|
322
179
|
```
|
|
323
|
-
|
|
324
|
-
**RIGHT** (palette token - stays in sync with the theme):
|
|
325
180
|
```css
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
--ig-avatar-background: var(--ig-primary-500);
|
|
329
|
-
--ig-avatar-color: var(--ig-primary-500-contrast);
|
|
330
|
-
}
|
|
331
|
-
|
|
332
|
-
/* MyView.razor.css - isolation file: same tokens, add ::deep */
|
|
333
|
-
::deep igc-avatar {
|
|
334
|
-
--ig-avatar-background: var(--ig-primary-500);
|
|
335
|
-
--ig-avatar-color: var(--ig-primary-500-contrast);
|
|
336
|
-
}
|
|
181
|
+
igc-nav-drawer { --menu-full-width: 260px; --menu-mini-width: 60px; }
|
|
182
|
+
.app-shell { display: flex; height: 100vh; }
|
|
337
183
|
```
|
|
338
184
|
|
|
339
|
-
|
|
340
|
-
If `create_theme` returns a luminance warning for a generated surface, do not ignore it. If the design needs multiple surface depths, use `create_custom_palette` or define semantic CSS variables such as `--surface-1` and `--surface-2` in the global CSS file instead of relying on a single generated surface color.
|
|
185
|
+
Width comes from `--menu-full-width` — no `::part()` override needed. Content in `slot="mini"` shows while the drawer is closed, giving an icon rail. Do not call `ShowAsync()` from `OnAfterRenderAsync`; the component is not ready. Drive it with `Open`.
|
|
341
186
|
|
|
342
|
-
|
|
187
|
+
### Icons in slots must be `IgbIcon`
|
|
343
188
|
|
|
344
|
-
|
|
189
|
+
A font-icon `<span>` is `display: inline`, so `vertical-align` is ignored by the slot's flex container and the glyph drifts to the top. `IgbIcon` is `inline-flex; align-items: center` and self-centers.
|
|
345
190
|
|
|
346
|
-
### Adding markers programmatically
|
|
347
|
-
Map series are added as child components in Razor markup, not programmatically:
|
|
348
191
|
```razor
|
|
349
|
-
<
|
|
350
|
-
|
|
351
|
-
DataSource="Locations"
|
|
352
|
-
LatitudeMemberPath="Lat"
|
|
353
|
-
LongitudeMemberPath="Lon"
|
|
354
|
-
MarkerType="MarkerType.Circle"
|
|
355
|
-
MarkerBrush="#FF5722" />
|
|
356
|
-
</IgbGeographicMap>
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
### Dark map styling
|
|
360
|
-
OpenStreetMap tiles are light by default. For dark themes, apply a CSS filter to the map container. Adjust the values to match the map tone in the design image:
|
|
361
|
-
```css
|
|
362
|
-
.map-container {
|
|
363
|
-
/* tune grayscale (0-1) and brightness (0-1) to match the design */
|
|
364
|
-
filter: grayscale(0.8) brightness(0.6);
|
|
365
|
-
}
|
|
192
|
+
@* ❌ *@ <IgbInput><span slot="prefix" class="material-icons">search</span></IgbInput>
|
|
193
|
+
@* ✅ *@ <IgbInput><IgbIcon @ref="_icon" slot="prefix" IconName="search" Collection="material" /></IgbInput>
|
|
366
194
|
```
|
|
367
195
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
## Dark Theme Specifics
|
|
196
|
+
The parameter is `IconName`; `Name` is the framework's element identity on every component. Register the icon in `OnAfterRenderAsync(firstRender)` after `await EnsureReady()`, or nothing renders.
|
|
371
197
|
|
|
372
|
-
###
|
|
373
|
-
Switch the theme `<link>` from light to dark:
|
|
374
|
-
```html
|
|
375
|
-
<!-- Light -->
|
|
376
|
-
<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />
|
|
377
|
-
<!-- Dark -->
|
|
378
|
-
<link href="_content/IgniteUI.Blazor/themes/dark/bootstrap.css" rel="stylesheet" />
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
> **If the view includes any full-featured grid**, switch the grid-specific stylesheet variant too:
|
|
382
|
-
> ```html
|
|
383
|
-
> <!-- Light -->
|
|
384
|
-
> <link href="_content/IgniteUI.Blazor/themes/grid/light/bootstrap.css" rel="stylesheet" />
|
|
385
|
-
> <!-- Dark -->
|
|
386
|
-
> <link href="_content/IgniteUI.Blazor/themes/grid/dark/bootstrap.css" rel="stylesheet" />
|
|
387
|
-
> ```
|
|
388
|
-
>
|
|
389
|
-
> **If the view uses `IgbGridLite`**, switch its single stylesheet instead:
|
|
390
|
-
> ```html
|
|
391
|
-
> <!-- Light -->
|
|
392
|
-
> <link href="_content/IgniteUI.Blazor.GridLite/css/themes/light/bootstrap.css" rel="stylesheet" />
|
|
393
|
-
> <!-- Dark -->
|
|
394
|
-
> <link href="_content/IgniteUI.Blazor.GridLite/css/themes/dark/bootstrap.css" rel="stylesheet" />
|
|
395
|
-
> ```
|
|
396
|
-
|
|
397
|
-
### CSS custom properties for dark panels
|
|
398
|
-
When the design has multiple dark surface depths (e.g., sidebar darker than content area), define semantic tokens:
|
|
399
|
-
```css
|
|
400
|
-
:root {
|
|
401
|
-
--surface-1: var(--ig-gray-900); /* deepest (sidebar, drawer) */
|
|
402
|
-
--surface-2: var(--ig-gray-800); /* content area */
|
|
403
|
-
--surface-3: var(--ig-gray-700); /* elevated cards/panels */
|
|
404
|
-
}
|
|
405
|
-
```
|
|
198
|
+
### `Name` never groups or names a form field
|
|
406
199
|
|
|
407
|
-
|
|
200
|
+
`<IgbRadioGroup Name="plan">` does not group radios — being children of the group does, and the selection is the group's `@bind-Value`.
|
|
408
201
|
|
|
409
|
-
###
|
|
410
|
-
Swap the CSS `<link>` element via JS interop:
|
|
411
|
-
```html
|
|
412
|
-
<script>
|
|
413
|
-
window.themeSwitcher = {
|
|
414
|
-
setTheme(href) {
|
|
415
|
-
document.getElementById('theme-css').href = href;
|
|
416
|
-
}
|
|
417
|
-
};
|
|
418
|
-
</script>
|
|
419
|
-
```
|
|
202
|
+
### `IgbAvatar` uses `Shape`
|
|
420
203
|
|
|
421
|
-
|
|
422
|
-
await JS.InvokeVoidAsync(
|
|
423
|
-
"themeSwitcher.setTheme",
|
|
424
|
-
"_content/IgniteUI.Blazor/themes/dark/bootstrap.css");
|
|
425
|
-
```
|
|
204
|
+
`AvatarShape.Circle | Rounded | Square`. There is no `RoundShape`.
|
|
426
205
|
|
|
427
|
-
|
|
206
|
+
### `IgbCombo`'s generic parameter is `T`
|
|
428
207
|
|
|
429
|
-
|
|
208
|
+
`<IgbCombo T="Person" …>`, not `TValue`.
|
|
430
209
|
|
|
431
|
-
|
|
210
|
+
### `IgbCard` has no default width
|
|
432
211
|
|
|
433
|
-
|
|
212
|
+
Always set one.
|
|
434
213
|
|
|
435
|
-
|
|
214
|
+
### `IgbTileManager` drag and resize modes
|
|
436
215
|
|
|
437
|
-
|
|
438
|
-
@* WRONG - RZ9986 build failure *@
|
|
439
|
-
<IgbChip class="chip @(item == _selected ? "chip-active" : "")" />
|
|
440
|
-
```
|
|
216
|
+
`DragMode`: `None | TileHeader | Tile`. `ResizeMode`: `None | Hover | Always`.
|
|
441
217
|
|
|
442
|
-
|
|
218
|
+
### Grids need a height
|
|
443
219
|
|
|
444
|
-
|
|
445
|
-
@* RIGHT - no RZ9986 *@
|
|
446
|
-
<IgbChip class="@ChipClass(item)" />
|
|
220
|
+
Without one the grid renders every row and virtualization is off. Also remember the **grid-specific stylesheet** alongside the base theme for any full-featured grid.
|
|
447
221
|
|
|
448
|
-
|
|
449
|
-
private string ChipClass(Item item) =>
|
|
450
|
-
item == _selected ? "chip chip-active" : "chip";
|
|
451
|
-
}
|
|
452
|
-
```
|
|
222
|
+
## Dark themes
|
|
453
223
|
|
|
454
|
-
|
|
224
|
+
Switch both stylesheets together:
|
|
455
225
|
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
typeof(IgbCategoryChartModule),
|
|
461
|
-
typeof(IgbListModule),
|
|
462
|
-
typeof(IgbNavbarModule)
|
|
463
|
-
);
|
|
226
|
+
```html
|
|
227
|
+
<link href="_content/IgniteUI.Blazor/themes/dark/bootstrap.css" rel="stylesheet" />
|
|
228
|
+
<link href="_content/IgniteUI.Blazor/themes/grid/dark/bootstrap.css" rel="stylesheet" />
|
|
229
|
+
<!-- IgbGridLite instead: _content/IgniteUI.Blazor.GridLite/css/themes/dark/bootstrap.css -->
|
|
464
230
|
```
|
|
465
231
|
|
|
466
|
-
|
|
467
|
-
Blazor uses `@bind-Value`, `@bind-Checked`, etc. Verify the exact bindable parameter from the component docs before inventing one:
|
|
468
|
-
```razor
|
|
469
|
-
<IgbInput @bind-Value="searchText" />
|
|
470
|
-
<IgbSwitch @bind-Checked="isDarkMode" />
|
|
471
|
-
```
|
|
232
|
+
For a runtime toggle, prefer `IgbThemeProvider` (`Theme`, `Variant`) over swapping `<link href>` via JS interop — no interop and it can scope to a region.
|
|
472
233
|
|
|
473
|
-
|
|
474
|
-
Use the event pattern shown in the Blazor docs for that component. Native click handling on Ignite UI buttons commonly uses Blazor's `@onclick`; component events use their PascalCase event names:
|
|
475
|
-
```razor
|
|
476
|
-
<IgbButton @onclick="HandleClick">Save</IgbButton>
|
|
477
|
-
<IgbGrid RowSelectionChanging="OnRowSelection" />
|
|
234
|
+
**Multiple surface depths.** A single generated surface will not cover a sidebar darker than the content area. Define semantic variables and use them in layout CSS:
|
|
478
235
|
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
236
|
+
```css
|
|
237
|
+
:root {
|
|
238
|
+
--surface-1: var(--ig-gray-900); /* sidebar */
|
|
239
|
+
--surface-2: var(--ig-gray-800); /* content */
|
|
240
|
+
--surface-3: var(--ig-gray-700); /* elevated cards */
|
|
482
241
|
}
|
|
483
242
|
```
|
|
484
243
|
|
|
485
|
-
|
|
486
|
-
Ignite UI Blazor uses `<Template>` child elements with the `context` parameter - not Angular's `<ng-template>`:
|
|
487
|
-
```razor
|
|
488
|
-
<IgbGrid Data="Data">
|
|
489
|
-
<IgbColumn Field="Name" Header="Name">
|
|
490
|
-
<Template>
|
|
491
|
-
<div>
|
|
492
|
-
<strong>@context.Cell.Value</strong>
|
|
493
|
-
</div>
|
|
494
|
-
</Template>
|
|
495
|
-
</IgbColumn>
|
|
496
|
-
</IgbGrid>
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
### `@ref` for programmatic access
|
|
500
|
-
Use `@ref` with a matching field of the component type:
|
|
501
|
-
```razor
|
|
502
|
-
<IgbDialog @ref="dialog">
|
|
503
|
-
<p>Dialog content</p>
|
|
504
|
-
</IgbDialog>
|
|
505
|
-
|
|
506
|
-
@code {
|
|
507
|
-
private IgbDialog dialog = default!;
|
|
244
|
+
Grid headers and rows often need explicit backgrounds to match the design's hierarchy in dark mode:
|
|
508
245
|
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
246
|
+
```css
|
|
247
|
+
igc-grid {
|
|
248
|
+
--ig-grid-header-background: var(--ig-surface-500);
|
|
249
|
+
--ig-grid-content-background: var(--ig-surface-500);
|
|
250
|
+
--ig-grid-row-hover-background: var(--ig-gray-100);
|
|
513
251
|
}
|
|
514
252
|
```
|
|
515
253
|
|
|
516
|
-
|
|
517
|
-
Use C# `record` or `class` types for mock data - not TypeScript interfaces:
|
|
518
|
-
```csharp
|
|
519
|
-
record SalesRecord(string Month, double Revenue, double Profit);
|
|
520
|
-
record Contact(string Name, string Email, string Initials);
|
|
521
|
-
```
|
|
522
|
-
|
|
523
|
-
### Avoid inline styles - use CSS isolation
|
|
524
|
-
Keep layout, spacing, typography, and surface styling in `.razor.css` files rather than using `style=""` inline attributes. This makes theming consistent and maintainable.
|
|
525
|
-
|
|
526
|
-
### Parameter naming: PascalCase
|
|
527
|
-
Blazor component parameters use PascalCase (`ChartType`, `DataSource`, `MarkerTypes`) - not Angular's camelCase bindings (`[chartType]`, `[dataSource]`, `[markerTypes]`).
|
|
528
|
-
|
|
529
|
-
### Single quotes in Razor attribute expressions cause CS1012
|
|
530
|
-
In Razor, `@onclick="() => Navigate('/dashboard')"` fails because the single quotes inside the double-quoted attribute are parsed as C# `char` literals, producing error CS1012. Use a named method or a variable instead:
|
|
531
|
-
```razor
|
|
532
|
-
@* WRONG - single quotes parsed as char literal *@
|
|
533
|
-
<IgbNavDrawerItem @onclick="() => Navigate('/dashboard')">
|
|
534
|
-
|
|
535
|
-
@* RIGHT - use a method reference or extract the path *@
|
|
536
|
-
<IgbNavDrawerItem @onclick="NavigateToDashboard">
|
|
537
|
-
|
|
538
|
-
@code {
|
|
539
|
-
private void NavigateToDashboard() => NavigationManager.NavigateTo("/dashboard");
|
|
540
|
-
}
|
|
541
|
-
```
|
|
542
|
-
This applies to any inline lambda where a string literal containing `/` or special chars appears inside a double-quoted Razor attribute. Prefer named handler methods over inline lambdas with string arguments.
|
|
254
|
+
**No hardcoded hex after the palette exists.** Core component colors come from palette tokens (`var(--ig-primary-500)`, `var(--ig-primary-500-contrast)`) so theme switching keeps working. Chart, map, gauge and sparkline parameters are the exception — they need resolved color values.
|