Updating to Angular Material 18: Keeping Support for Material 2 and Adding Support for Material 3
Tags: anguar, angularmaterial, materialdesign, webdev
Published: 2024-05-25 12:22:37

---
title: Updating to Angular Material 18: Keeping Support for Material 2 and Adding Support for Material 3
published: true
description: In this article, we will update Angular Material 17 to 18, with Material 2 and also Material 3
tags: anguar,angularmaterial,materialdesign,webdevelopment
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/13g1jl9wheevjh0nrd6f.png
canonical_url: https://angular-material.dev/articles/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 <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

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

[![button image with link to GitHub sponsor profile of Dharmen Shah](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3kp126mnzcpl1a4czppg.png)](https://github.com/sponsors/shhdharmen)

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