Updating to Angular Material 18

> In this quick guide, we will update an Angular project with Angular Material 17 to 18. And we will also learn how to keep support for M2 and add support for M3 ## Existing Project For this guide, I am going to use the project [course-md-ng-my-app](https://github.com/Angular-Material-Dev/course-md-ng-my-app/tree/angular-material-17) from my course. You can clone it using below commands: ```bash git clone https://github.com/Angular-Material-Dev/course-md-ng-my-app --branch angular-material-17 cd course-md-ng-my-app npm i ``` ## Finding the updates We will first find out the updates using Angular CLI's update command: ```bash ng update ``` You should see the output like below: ```bash Name Version Command to update -------------------------------------------------------------------------------- @angular/cdk 17.3.10 -> 18.0.0 ng update @angular/cdk @angular/cli 17.3.8 -> 18.0.1 ng update @angular/cli @angular/core 17.3.10 -> 18.0.0 ng update @angular/core @angular/material 17.3.10 -> 18.0.0 ng update @angular/material ``` ## Update Angular CLI to 18 ```bash ng update @angular/cli@18 ``` When asked about migrating to the new build system, I am going to select it using `space` and press `enter`. As it's optional, you can skip it. ```bash Select the migrations that you'd like to run (Press to select, to toggle all, to invert selection, and to proceed) ❯◯ [use-application-builder] Migrate application projects to the new build system. (https://angular.dev/tools/cli/build-system-migration) ``` ### Check your app After updating Angular CLI to 18, please check the application by running `npm start` command. ## Update Angular Material to 18 ```bash ng update @angular/material@18 ``` Above command will update both, `@angular/material` and `@angular/cdk` to version 18. Now, Angular Material did not provide schematic support to migrate SASS theme APIs to latest ones. So, if you run the project now, you will see many errors. We will try to resolve them one-by-one. ## Keeping Support for Material 2 (M2) First, we will make changes in such a way that our application still follows Material 2 designs. If you want to simply update your application for Material 3 (M3), jump to [Adding support for Material 3 (M3)](#adding-support-for-material-3-m3) Each section will have a table with 2 columns, **old** and **new**. Simply find and replace value from *old* with value from *new* in whole project. ### Typography changes for M2 | Index | Old | New | | ----- | -------------------------- | ----------------------------- | | 1 | `define-typography-config` | `m2-define-typography-config` | | 2 | `define-typography-level` | `m2-define-typography-level` | ### Color palettes changes for M2 | Index | Old | New | | ----- | ---------------- | ------------------- | | 1 | `define-palette` | `m2-define-palette` | #### Predefined palettes changes for M2 If you're using any pre-defined palette, like `mat.$indigo-palette`, pre-fix the variable with `m2`. So, new palette would become `mat.$m2-indigo-palette` ### Theming changes for M2 | Index | Old | New | | ----- | -------------------- | ----------------------- | | 1 | `define-light-theme` | `m2-define-light-theme` | | 2 | `define-dark-theme` | `m2-define-dark-theme` | #### Adding typography for dark theme As we are going to lazy load the dark theme, we need to include `typography` in it. So, until now, the dark theme looks like below: ```scss // Define a dark theme $my-app-dark-theme: mat.m2-define-dark-theme( ( color: ( primary: mat.m2-define-palette(mat.$m2-pink-palette), accent: mat.m2-define-palette(mat.$m2-blue-grey-palette), ), ) ); ``` Simply add `typography` in the map like below: ```scss // Define a dark theme $my-app-dark-theme: mat.m2-define-dark-theme( ( color: ( primary: mat.m2-define-palette(mat.$m2-pink-palette), accent: mat.m2-define-palette(mat.$m2-blue-grey-palette), ), typography: config.$my-app-typography, // 👈 Added ) ); ``` ### Changes for custom component In this project, we have a custom component at `ui/alert`, in that we are using Material theme (colors and typography) using Angular Material SASS mixins and functions. In this section, we will look into changes needed for making it compatible with Angular Material 18. The file we are targeting is at `src/app/ui/alert/_alert-theme.scss`. #### TL;DR If you simply want to check the final code, it will look like below: ```scss // _alert-theme.scss @use "sass:map"; @use "@angular/material" as mat; @mixin color($theme) { $type: mat.get-theme-type($theme); $is-dark-theme: $type == dark; $exportBackgroundOpacity: if($is-dark-theme, 0.12, 0.06); .alert { color: mat.get-theme-color( $theme, primary, if($is-dark-theme, 50, default) ); background: rgba( mat.get-theme-color($theme, primary, 300), $exportBackgroundOpacity ); border-color: mat.get-theme-color($theme, primary, 100); .alert-link { color: mat.get-theme-color($theme, primary, if($is-dark-theme, 200, 500)); } } } @mixin typography($theme) { .alert { font: mat.get-theme-typography($theme, body-1); letter-spacing: mat.get-theme-typography($theme, body-1, letter-spacing); .alert-heading { font: mat.get-theme-typography($theme, "headline-6"); } .alert-footer { font: mat.get-theme-typography($theme, "caption"); } } } @mixin theme($theme) { @include color($theme); @include typography($theme); } ``` With above changes, you component should work fine. If you want to know more about the changes, keep reading on, else jump to [next section](#checking-all-the-changes-for-m2). #### Reading color values If you look at the code, we are using `get-color-config` function, but it is removed now. And with it `get-color-from-palette` function is also removed. So, now to get any color from theme, we have to use `get-theme-color`. You can read about it at [here](https://material.angular.io/guide/material-2-theming#reading-color-values). #### Identifying the current theme We also can't use `map.get($theme, is-dark)` anymore. There is a new function to identify the type of theme: `mat.get-theme-type($theme)`. This function takes a single argument, the theme, and returns either `light` or `dark`. #### Reading typography values `mat.font-family` and `mat.typography-level` are also removed. There is a new function called `get-theme-typography`, you can read more about it [here](https://material.angular.io/guide/material-2-theming#reading-typography-values). ### Checking all the changes for M2 After making all the changes, you should be good to run the project without any errors. You can also take a look at all the changes needed for keeping M2 support with Angular Material 18 at the the PR: [feat: keeping m2 support with angular material 18](https://github.com/Angular-Material-Dev/course-md-ng-my-app/pull/1/files). ## Adding Support for Material 3 (M3) If you want to add support for M3 with Angular Material 18, simply follow guidelines from [Theming Angular Material](https://material.angular.io/guide/theming). Angular Material team has already given in-depth guidelines about it. The changes needed to add support for M3 with Angular Material 18 for the project can be viewed at the commit on GitHub: [feat: add support for M3 with angular material 18](https://github.com/Angular-Material-Dev/course-md-ng-my-app/commit/e39cd37595d6e38ca3f6023b2c928c60a7a0a0c8). ## Support ## Conclusion We started with cloning the existing repo with Angular Material 17 from one my other courses. Then we looked at updates needed by running `ng update` command. And then we ran `ng update @angular/cli@18` and `ng update @angular/material@18` in sequence. We started with keeping support for M2. We learned that what functions are removed and what we can use instead of them. And at last we saw how to add support for M3 with Angular Material 18. Below is the quick summary: | Index | Applies to | Old | Change for M2 | Change for M3 | | ----- | ----------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Typography | `define-typography-config` | [`m2-define-typography-config`](https://material.angular.io/guide/material-2-theming#typography-config) | [Part of `define-theme`](https://material.angular.io/guide/theming#customizing-your-typography) | | 2 | Typography | `define-typography-level` | [`m2-define-typography-level`](https://material.angular.io/guide/material-2-theming#define-a-level) | [`get-theme-typography`](https://material.angular.io/guide/theming-your-components#reading-typescale-properties) | | 3 | Color palettes | `define-palette` | [`m2-define-palette`](https://material.angular.io/guide/material-2-theming#:~:text=warn%20palette.%20The-,m2%2Ddefine%2Dpalette,-Sass%20function%20accepts) | SASS Map, can be generated using [Material 3 Theme schematic](https://material.angular.io/guide/schematics#material-3-theme-schematic) | | 4 | Color palettes | `$indigo-palette` | [`$m2-indigo-palette`](https://material.angular.io/guide/material-2-theming#predefined-palettes), [All Palettes](https://m1.material.io/style/color.html#color-color-palette) | `$azure-palette`, [All Palettes](https://material.angular.io/guide/theming#pre-built-themes) | | 5 | Theming | `define-light-theme` | [`m2-define-light-theme`](https://material.angular.io/guide/material-2-theming#defining-a-theme) | [`define-theme`](https://material.angular.io/guide/theming#defining-a-theme) | | 6 | Theming | `define-dark-theme` | [`m2-define-dark-theme`](https://material.angular.io/guide/material-2-theming#defining-a-theme) | [`define-theme`](https://material.angular.io/guide/theming#defining-a-theme) | | 7 | Reading color values | `get-color-config` | Removed | Removed | | 8 | Reading color values | `get-color-from-palette` | [`get-theme-color`](https://material.angular.io/guide/material-2-theming#reading-color-values) | `get-theme-color`, [Reading tonal palette colors](https://material.angular.io/guide/theming-your-components#reading-tonal-palette-colors), [Reading color roles](https://material.angular.io/guide/theming-your-components#reading-color-roles) | | 9 | Identifying the current theme | `map.get($theme, is-dark)` | [`get-theme-type`](https://material.angular.io/guide/material-2-theming#reading-color-values:~:text=can%20use%20the-,get%2Dtheme%2Dtype,-Sass%20function%20to) | [`get-theme-type`](https://material.angular.io/guide/theming-your-components#reading-the-theme-type) | | 10 | Reading typography values | `font-family` | Removed | Removed | | 11 | Reading typography values | `typography-level` | [`get-theme-typography`](https://material.angular.io/guide/material-2-theming#reading-typography-values) | [`get-theme-typography`](https://material.angular.io/guide/theming-your-components#reading-typescale-properties) | | 12 | Reading density values | `get-theme-density` | *No change* [`get-theme-density`](https://material.angular.io/guide/material-2-theming#reading-density-values) | *No change* [`get-theme-density`](https://material.angular.io/guide/theming-your-components#reading-the-density-scale) | ## Codes Codes and changes are available as below: | Index | Branch | Angular Material Version | Material Design version | PR/Commit | | ----- | ----------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | | 1 | [main](https://github.com/Angular-Material-Dev/course-md-ng-my-app) | 18 | 3 | [e39cd37](https://github.com/Angular-Material-Dev/course-md-ng-my-app/commit/e39cd37595d6e38ca3f6023b2c928c60a7a0a0c8) | | 2 | [angular-material-18-m2](https://github.com/Angular-Material-Dev/course-md-ng-my-app/tree/angular-material-18-m2) | 18 | 2 | [PR#1](https://github.com/Angular-Material-Dev/course-md-ng-my-app/pull/1) | | 3 | [angular-material-17](https://github.com/Angular-Material-Dev/course-md-ng-my-app/tree/angular-material-17) | 17 | 2 | -- |