diff --git a/en/components/accordion.md b/en/components/accordion.md index a4c850fa20..8e942cc582 100644 --- a/en/components/accordion.md +++ b/en/components/accordion.md @@ -294,7 +294,9 @@ $custom-panel-theme: expansion-panel-theme( The last step is to include the component's theme. ```scss -@include css-vars($custom-panel-theme); +:host { + @include tokens($custom-panel-theme); +} ``` ### Demo diff --git a/en/components/action-strip.md b/en/components/action-strip.md index 411c409d2c..ab815d5ea5 100644 --- a/en/components/action-strip.md +++ b/en/components/action-strip.md @@ -185,7 +185,9 @@ $custom-strip: action-strip-theme( The last step is to include the newly created component theme in our application. ```scss -@include css-vars($custom-strip); +:host { + @include tokens($custom-strip); +} ``` -- [Getting Started with Ignite UI for Angular](getting-started.md) -- [Angular Schematics & Ignite UI CLI](cli-overview.md) -- [How to Use Standalone Components](how-to/how-to-use-standalone-components.md) -- [Code Splitting and Multiple Entry Points](code-splitting-and-multiple-entry-points.md) +- [Getting Started with Ignite UI for Angular](../general/getting-started.md) +- [Angular Schematics & Ignite UI CLI](../general/cli-overview.md) +- [How to Use Standalone Components](../general/how-to/how-to-use-standalone-components.md) +- [Code Splitting and Multiple Entry Points](../general/code-splitting-and-multiple-entry-points.md)
Our community is active and always welcoming to new ideas. diff --git a/en/components/themes/mcp.md b/en/components/ai/theming-mcp.md similarity index 97% rename from en/components/themes/mcp.md rename to en/components/ai/theming-mcp.md index f5f15e9327..021440d451 100644 --- a/en/components/themes/mcp.md +++ b/en/components/ai/theming-mcp.md @@ -292,7 +292,7 @@ $my-typography: typography( > _"Our design system specifies exact hex values for all 14 shades of our primary green. I'll paste the values — create a custom palette."_ -The AI will call `create_custom_palette` with `mode: "explicit"` for the primary color and auto-generate the rest. See [Palettes](./palettes.md) for more detail on shade generation. +The AI will call `create_custom_palette` with `mode: "explicit"` for the primary color and auto-generate the rest. See [Palettes](../themes/palettes.md) for more detail on shade generation. ### Component-Level Customization @@ -328,19 +328,19 @@ Ensure `igniteui-angular` and `igniteui-theming` are installed: ng add igniteui-angular ``` -Also confirm that `core()` is called before any other theming mixin in your `styles.scss`. See [Theming with Sass](./sass/index.md) for the correct file setup. +Also confirm that `core()` is called before any other theming mixin in your `styles.scss`. See [Theming with Sass](../themes/sass/index.md) for the correct file setup. ## Additional Resources Related topics: -- [Theming Overview](./index.md) -- [Palettes](./palettes.md) -- [Typography](./typography.md) -- [Elevations](./elevations.md) -- [Spacing](./spacing.md) -- [Roundness](./roundness.md) -- [Theming with Sass](./sass/index.md) +- [Theming Overview](../themes/index.md) +- [Palettes](../themes/palettes.md) +- [Typography](../themes/typography.md) +- [Elevations](../themes/elevations.md) +- [Spacing](../themes/spacing.md) +- [Roundness](../themes/roundness.md) +- [Theming with Sass](../themes/sass/index.md)
diff --git a/en/components/avatar.md b/en/components/avatar.md index a478232d5e..aeb825152d 100644 --- a/en/components/avatar.md +++ b/en/components/avatar.md @@ -208,7 +208,7 @@ The last step is to pass the custom avatar theme: ```scss .initials { - @include css-vars($custom-avatar-theme); + @include tokens($custom-avatar-theme); } ``` @@ -270,7 +270,7 @@ igx-avatar { } ``` -Or you can use the universal `--igx-avatar-size` variable to target all instances: +Or you can use the universal `--ig-avatar-size` variable to target all instances: ```html
@@ -280,7 +280,7 @@ Or you can use the universal `--igx-avatar-size` variable to target all instance ```scss .my-app { - --igx-avatar-size: 200px; + --ig-avatar-size: 200px; } ``` diff --git a/en/components/badge.md b/en/components/badge.md index 67830a8743..b95e1d7b13 100644 --- a/en/components/badge.md +++ b/en/components/badge.md @@ -345,10 +345,12 @@ $custom-badge-theme: badge-theme( ); ``` -To include the new theme we use the `css-vars` mixin: +To include the new theme we use the `tokens` mixin: ```scss -@include css-vars($custom-badge-theme); +:host { + @include tokens($custom-badge-theme); +} ``` ### Demo diff --git a/en/components/banner.md b/en/components/banner.md index 4df3b2c854..a6c3ab70cb 100644 --- a/en/components/banner.md +++ b/en/components/banner.md @@ -286,7 +286,9 @@ $custom-banner-theme: banner-theme( The last step is to pass the custom banner theme: ```scss -@include css-vars($custom-banner-theme); +:host { + @include tokens($custom-banner-theme); +} ``` @@ -1558,7 +1558,7 @@ Or you can use the universal `--igx-button-size` variable to target all instance ```scss .my-app { - --igx-button-size: 50px; + --ig-button-size: 50px; } ``` diff --git a/en/components/calendar.md b/en/components/calendar.md index d497254d67..7b809fc851 100644 --- a/en/components/calendar.md +++ b/en/components/calendar.md @@ -799,7 +799,9 @@ $custom-calendar-theme: calendar-theme( The last step is to pass the custom calendar theme: ```scss - @include css-vars($custom-calendar-theme); +:host { + @include tokens($custom-calendar-theme); +} ``` @@ -697,7 +699,7 @@ Or you can use the universal `--igx-chip-size` variable to target all instances: ```scss .my-app { - --igx-chip-size: 50px; + --ig-chip-size: 50px; } ``` diff --git a/en/components/circular-progress.md b/en/components/circular-progress.md index 3269613129..9f5ce120d8 100644 --- a/en/components/circular-progress.md +++ b/en/components/circular-progress.md @@ -250,7 +250,9 @@ $custom-theme: progress-circular-theme( The last step is to **include** the component theme in our application. ```scss -@include css-vars($custom-theme); +:host { + @include tokens($custom-theme); +} ``` ### Demo diff --git a/en/components/combo.md b/en/components/combo.md index e73228470b..f6a288e966 100644 --- a/en/components/combo.md +++ b/en/components/combo.md @@ -387,10 +387,10 @@ $custom-checkbox-theme: checkbox-theme( The last step is to include the component's theme. ```scss -:host ::ng-deep { - @include css-vars($custom-combo-theme); - @include css-vars($custom-drop-down-theme); - @include css-vars($custom-checkbox-theme); +:host { + @include tokens($custom-combo-theme); + @include tokens($custom-drop-down-theme); + @include tokens($custom-checkbox-theme); } ``` diff --git a/en/components/date-picker.md b/en/components/date-picker.md index cbaef0dd81..4a955ff45f 100644 --- a/en/components/date-picker.md +++ b/en/components/date-picker.md @@ -336,7 +336,9 @@ $custom-datepicker-theme: calendar-theme( The last step is to pass the custom Date Picker theme: ```scss -@include css-vars($custom-datepicker-theme); +:host { + @include tokens($custom-datepicker-theme); +} ``` >[!WARNING] @@ -345,7 +347,7 @@ The last step is to pass the custom Date Picker theme: ```scss :host { ::ng-deep { - @include css-vars($custom-datepicker-theme); + @include tokens($custom-datepicker-theme); } } ``` diff --git a/en/components/date-range-picker.md b/en/components/date-range-picker.md index 9ee038d480..1ea9d11e82 100644 --- a/en/components/date-range-picker.md +++ b/en/components/date-range-picker.md @@ -535,9 +535,11 @@ $custom-calendar-theme: calendar-theme( The last step is to pass the custom themes: ```scss -@include css-vars($custom-date-range-theme); -@include css-vars($custom-input-group-theme); -@include css-vars($custom-calendar-theme); +:host { + @include tokens($custom-date-range-theme); + @include tokens($custom-input-group-theme); + @include tokens($custom-calendar-theme); +} ``` >[!WARNING] diff --git a/en/components/dialog.md b/en/components/dialog.md index 59c810d746..6328b938d9 100644 --- a/en/components/dialog.md +++ b/en/components/dialog.md @@ -338,7 +338,9 @@ Since the dialog window uses the [`IgxOverlayService`](overlay.md), in order for The last step is to **include** the component theme in our application. ```scss -@include css-vars($my-dialog-theme); +:host { + @include tokens($my-dialog-theme); +} ``` >[!NOTE] @@ -347,7 +349,7 @@ The last step is to **include** the component theme in our application. ```scss :host { ::ng-deep { - @include css-vars($my-dialog-theme); + @include tokens($my-dialog-theme); } } ``` diff --git a/en/components/drop-down.md b/en/components/drop-down.md index 08dfae8287..e88cff82f8 100644 --- a/en/components/drop-down.md +++ b/en/components/drop-down.md @@ -635,11 +635,11 @@ $custom-drop-down-theme: drop-down-theme( ); ``` -The last step is to pass the custom drop-down theme to a class or element selector: +The last step is to pass the custom drop-down theme: ```scss -.drop-down__scroll-container { - @include css-vars($custom-drop-down-theme); +:host { + @include tokens($custom-drop-down-theme); } ``` diff --git a/en/components/expansion-panel.md b/en/components/expansion-panel.md index fbb3bb6e4f..0f4419533a 100644 --- a/en/components/expansion-panel.md +++ b/en/components/expansion-panel.md @@ -335,11 +335,13 @@ $custom-panel-theme: expansion-panel-theme( ### Applying the Component Theme -Now to apply the component theme all that's left is to include `css-vars` mixin and pass the `$custom-panel-theme` map. +Now to apply the component theme all that's left is to include `tokens` mixin and pass the `$custom-panel-theme` map. ```scss // In expansion-styling.component.scss -@include css-vars($custom-panel-theme); +:host { + @include tokens($custom-panel-theme); +} ``` To find out more on how you can use Ignite UI theming engine [`click here`](themes/sass/component-themes.md) diff --git a/en/components/general/getting-started.md b/en/components/general/getting-started.md index 2cd668c3b6..bfcfd32293 100644 --- a/en/components/general/getting-started.md +++ b/en/components/general/getting-started.md @@ -306,13 +306,13 @@ In this article we learned how to create our own Ignite UI for Angular applicati Ignite UI for Angular ships with **Agent Skills** — structured knowledge files that teach AI coding assistants (GitHub Copilot, Cursor, Windsurf, Claude, JetBrains AI, etc.) how to work with the library. Skills cover components, data grids, grid data operations, and theming. -Learn more in the [AI-Assisted Development](ai-assisted-development.md) topic. +Learn more in the [Ignite UI for Angular Skills](../ai/skills.md) topic. ## Additional Resources
-- [AI-Assisted Development](ai-assisted-development.md) +- [Ignite UI for Angular Skills](../ai/skills.md) - [Ignite UI CLI](https://github.com/IgniteUI/igniteui-cli) - [Ignite UI CLI Commands](https://github.com/IgniteUI/igniteui-cli/wiki#available-commands) - [Grid overview](../grid/grid.md) diff --git a/en/components/general/how-to/how-to-customize-theme.md b/en/components/general/how-to/how-to-customize-theme.md index 470192d18b..670fa87fd3 100644 --- a/en/components/general/how-to/how-to-customize-theme.md +++ b/en/components/general/how-to/how-to-customize-theme.md @@ -110,7 +110,9 @@ $toolbar-theme: grid-toolbar-theme( $background-color: $primary ); -@include css-vars($toolbar-theme); +:host { + @include tokens($toolbar-theme); +} /* END Grid Toolbar */ ``` @@ -186,7 +188,7 @@ Then our theme definition will go in the general scope, which we will use for th ``` >[!NOTE] -> I have switched the `igx-grid-toolbar` theme override to overriding just two of its variables, instead of reincluding all of the theme variables using [`css-vars()`]({environment:sassApiUrl}/themes#mixin-css-vars). +> I have switched the `igx-grid-toolbar` theme override to overriding just two of its variables, instead of reincluding all of the theme variables using [`tokens`]({environment:sassApiUrl}/themes#mixin-tokens). > All theme variables can be found in the [corresponding sass api doc]({environment:sassApiUrl}/themes#function-grid-toolbar-theme) and are equivalent to the sass variables, but prefixed with `--` instead of `$`. And the result now looks like this with light OS theme: diff --git a/en/components/general/update-guide.md b/en/components/general/update-guide.md index 6e6876b341..ff7fc2a5b6 100644 --- a/en/components/general/update-guide.md +++ b/en/components/general/update-guide.md @@ -60,6 +60,71 @@ Unfortunately not all changes can be automatically updated. Changes below are sp For example: if you are updating from version 6.2.4 to 7.1.0 you'd start from the "From 6.x .." section apply those changes and work your way up: +## From 21.0.x to 21.1.x + +Version 21.1.0 ships with a new `tokens` mixin that can be used in place of the now deprecated `css-vars` mixin of our Sass theming framework. On the surface, this is a cosmetic change, however, the new `tokens` mixin produces universal global component theme tokens that work across all of our Ignite UI frameworks. The `css-vars` mixin is now deprecated and will be removed in a future version, so we recommend switching to the new `tokens` mixin as soon as possible. + +The `tokens` mixin generates CSS variable tokens for components in `global` or `scoped` modes, with a universal `--ig-*` fallback chain and proper rewriting of local token references. + +**Global mode** (default) — emits universal `--ig-{component}-{property}` tokens. Local `var()` references are rewritten to their global equivalents so derived values (e.g., `adaptive-contrast`) resolve correctly at any scope. Sizable expressions are skipped; pass concrete values instead. + +```scss +// Input: +@include tokens(avatar-theme($background: red)); + +// Output: +:root { + --ig-avatar-background: red; + /* ... remaining avatar properties ... */ +} +``` + +**Scoped mode** — emits component-scoped variables (`--{property}`) with a fallback chain: configured prefix (`--igx-*`) -> universal (`--ig-*`) -> schema default. When called from the stylesheet root, the theme's `selector` is used to create the rule. When called inside a selector, both the current selector and the component selector receive the variables. Essentially, this yields the same result as the now deprecated `css-vars` mixin. + +```scss +// Input (from root): +@include tokens(avatar-theme($background: red), $mode: 'scoped'); + +// Output: +igx-avatar { + --background: var(--igx-avatar-background, var(--ig-avatar-background, red)); + /* ... remaining avatar properties ... */ +} +``` + +```scss +// Input (from within a selector): +.my-theme { + @include tokens(avatar-theme($background: red), $mode: 'scoped'); +} + +// Output: +.my-theme, +.my-theme igx-avatar { + --background: var(--igx-avatar-background, var(--ig-avatar-background, red)); + /* ... */ +} +``` + +> [!NOTE] +> In scoped mode, the `selector` property in the produced theme map is required to determine the component selector for proper variable scoping. If the mixin is called from the stylesheet root, the generated rule will use the theme's internal `selector` value. If called from within a selector, both that selector and the component selector will receive the variables. + +```scss +// Global override: +:root { + @include tokens(avatar-theme($background: orange)); +} +// Result: --ig-avatar-background: orange; + +// Scoped consumption (no explicit override): +@include tokens(avatar-theme($schema: $schema), $mode: 'scoped'); +// Result: --background resolves through var(--igx-avatar-background, var(--ig-avatar-background, #000)) +// and picks up the global orange value from --ig-avatar-background. +``` + +> [!IMPORTANT] +> **Global overrides flow into scoped mode.** Because scoped variables fall back to `--ig-*` tokens, setting a global token at `:root` will propagate to all scoped instances: + ## From 20.x to 21.0.x ### Multiple Entry Points Support diff --git a/en/components/grid-lite/binding.md b/en/components/grid-lite/binding.md index e832fb17db..7fe886ba01 100644 --- a/en/components/grid-lite/binding.md +++ b/en/components/grid-lite/binding.md @@ -24,10 +24,10 @@ grid.data = [...{ ``` ```html - + - - + + ``` If the grid has `autoGenerate` enabled, it will "_infer_" the new column configuration automatically when the data changes. @@ -39,6 +39,16 @@ grid.autoGenerate = true; grid.data = []; ``` +Or just set the respective properties in the html instead of using a `@ViewChild` for the grid. + +```html + + +``` + + >[!NOTE] >The sort/filter states of the Grid Lite component are kept when changing the data source in this manner. Usually you will want to reset them by calling either **`clearSort()`** and/or **`clearFilter()`**. diff --git a/en/components/grid-lite/cell-template.md b/en/components/grid-lite/cell-template.md index 8d9a72ce3f..70c7a6c737 100644 --- a/en/components/grid-lite/cell-template.md +++ b/en/components/grid-lite/cell-template.md @@ -11,18 +11,27 @@ namespace: Infragistics.Controls By default, the grid uses the field of the column to render the value as a string inside the cell. This is fine for basic scenarios, but if you want to customize the rendered output or the final output is a combination of different data fields, you can customize the cell template. -To achieve that, set the `cellTemplate` property of the column. +To achieve that, use **``** inside `...` of a column in which you want to template the content. + +```html + + + + + + +``` + +You also need to import **`IgxGridLiteCellTemplateDirective`** ```typescript -protected cellTemplate(params: IgcCellContext) { - // return template result -} +import { IgxGridLiteComponent, IgxGridLiteColumnComponent, IgxGridLiteCellTemplateDirective } from 'igniteui-angular/grids/lite'; ``` -```html - - - +And add it to the `imports` array + +```typescript +imports: [ IgxGridLiteCellTemplateDirective ] ``` ## Use as a Formatter Function @@ -30,10 +39,15 @@ protected cellTemplate(params: IgcCellContext) { For the simple scenario where some formatting is required, one can just return the formatted value. Here is an example for displaying a number value to a locale currency format: ```typescript -const { format: asCurrency } = new Intl.NumberFormat('en-EN', { style: 'currency', currency: 'EUR' }); +public formatter = new Intl.NumberFormat('en-150', { + style: 'currency', + currency: 'EUR' +}); /** Return the custom currency format for a value `value = 123456.789` */ -protected cellTemplate = (params) => asCurrency(params.value); // => "€123,456.79" +protected formatCurrency = (value: number) => { + return this.formatter.format(value); // => "€123,456.79" +}; ``` You can combine values different fields from the data source as well. @@ -41,41 +55,56 @@ You can combine values different fields from the data source as well. Refer to the API documentation for **`GridLiteCellContext`** for more information. --> ```typescript -const { format: asCurrency } = new Intl.NumberFormat('en-EN', { style: 'currency', currency: 'EUR' }); - -/** Return the custom currency format for an order of 10 items where the price is 99.99 */ -protected cellTemplate = ({value, row}) => asCurrency(value * row.data.count); // => "€999.90" +public formatter = new Intl.NumberFormat('en-150', { + style: 'currency', + currency: 'EUR' +}); + +/** Return the total earned money from a product in custom currency */ +protected formatCurrency = (value: number, unitsSold: number) => { + return this.formatter.format(value * unitsSold); +}; ``` ```html - - - + + + {{formatCurrency(value, row.data.sold)}} + + ``` ## Custom DOM Templates -Aside from using the **`cellTemplate`** property as a value formatter, you can also create your own DOM template, which -will be rendered inside the cell container. +Aside from using components from **`igniteui-angular`** inside the **``** , you can also create your own DOM template, which will be rendered inside the cell container. -We've decided to re-use the functionality provided by Lit and its -tagged template syntax for building declarative -DOM fragments. - -You can template any standard DOM elements as well as web components from other libraries. +You can template any standard DOM elements as well as web components from other libraries. For example in the following code snippets we are using the rating component coming from **`igniteui-webcomponents`**. In order to use it properly, we need to go through a few steps described below. ```typescript -// Import the `html` tag function from the Lit package. -import { html } from "lit"; - -// Use another web component to represent the `rating` value in the grid -protected cellTemplate = ({ value }) => html``; +// Import external components for the custom template +import { + defineComponents, + IgcRatingComponent +} from 'igniteui-webcomponents'; + +// Define them so that we can use them in our sample +defineComponents( + IgcRatingComponent +); ``` ```html - - - + + + + + + + ``` >[!NOTE] @@ -90,10 +119,7 @@ The custom cell renderer is passed an **`GridLiteCellContext`** object as a para /** * Context object for the row cell template callback. */ -export interface GridLiteCellContext< - T extends object, - K extends Keys = Keys -> { +export interface IgxGridLiteCellTemplateContext { /** * The cell element parent of the template. */ @@ -110,6 +136,8 @@ export interface GridLiteCellContext< * The value from the data source for this cell. */ value: PropertyType; + + $implicit: PropertyType; } ``` diff --git a/en/components/grid-lite/column-configuration.md b/en/components/grid-lite/column-configuration.md index 74a315570c..11c7afe7e5 100644 --- a/en/components/grid-lite/column-configuration.md +++ b/en/components/grid-lite/column-configuration.md @@ -12,14 +12,14 @@ namespace: Infragistics.Controls Columns are defined declaratively using column child components within the grid. The `field` property is the only required for a column, as it serves as the column identifier. It is also the property that is used to map and render the relevant data in the grid rows. ```html - - + + > - + ``` ## Configuration Based on the Data Source @@ -34,17 +34,17 @@ const data: Record[] = [ ``` ```html - + ``` The previous snippet will result in the grid automatically creating columns equivalent to: ```html - - - - - + + + + + ``` Useful for a quick render of some data without any additional customizations. @@ -65,7 +65,7 @@ in the grid width. To change the width of column, use the `width` property of the column. ```html - + ``` The property accepts valid CSS length units. @@ -75,7 +75,7 @@ The property accepts