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 from my course. You can clone it using below commands:
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:
ng update
You should see the output like below:
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
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.
Select the migrations that you'd like to run (Press <space> to select, <a> to toggle all, <i> to invert selection, and
<enter> 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
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)
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:
// 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:
// 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:
// _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.
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.
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.
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.
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. 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.
Support Free Content Creation
Even though the courses and articles are available at no cost, your support in my endeavor to deliver top-notch educational content would be highly valued. Your decision to contribute aids me in persistently improving the course, creating additional resources, and maintaining the accessibility of these materials for all. I'm grateful for your consideration to contribute and make a meaningful difference!
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 |
Part of define-theme |
2 | Typography | define-typography-level |
m2-define-typography-level |
get-theme-typography |
3 | Color palettes | define-palette |
m2-define-palette |
SASS Map, can be generated using Material 3 Theme schematic |
4 | Color palettes | $indigo-palette |
$m2-indigo-palette , All Palettes
|
$azure-palette , All Palettes
|
5 | Theming | define-light-theme |
m2-define-light-theme |
define-theme |
6 | Theming | define-dark-theme |
m2-define-dark-theme |
define-theme |
7 | Reading color values | get-color-config |
Removed | Removed |
8 | Reading color values | get-color-from-palette |
get-theme-color |
get-theme-color , Reading tonal palette colors, Reading color roles
|
9 | Identifying the current theme | map.get($theme, is-dark) |
get-theme-type |
get-theme-type |
10 | Reading typography values | font-family |
Removed | Removed |
11 | Reading typography values | typography-level |
get-theme-typography |
get-theme-typography |
12 | Reading density values | get-theme-density |
No change get-theme-density
|
No change get-theme-density
|
Codes
Codes and changes are available as below:
Index | Branch | Angular Material Version | Material Design version | PR/Commit |
---|---|---|---|---|
1 | main | 18 | 3 | e39cd37 |
2 | angular-material-18-m2 | 18 | 2 | PR#1 |
3 | angular-material-17 | 17 | 2 | -- |
Top comments (0)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.