Updating to Angular Material 18: Keeping Support for Material 2 and Adding Support for Material 3

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	--