Angular Material Theming System - Updating Angular Material 18 to 19

Demo in Angular Material 18

I am going to use the same demo as in the previous course, you can clone it from here.

Updating Angular Material 18 to 19

info Info

After any step, if you receive the below error, you can run npm start again.

An unhandled exception occurred: Builder must provide an initial full build before incremental results.

1. Checking for updates

ng update

2. Update Angular CLI

ng update @angular/cli

3. Update Angular Material

ng update @angular/material

Style changes for Angular Material 19

1. Updates in main theme file

We will start with making changes in main theme file at src/styles.scss.

1.1 Remove redundant mixin usages

As we already have them outside, remove usage of mat.elevation-classes and mat.app-background mixins from withing :root selector.

1
@include mat.elevation-classes();
2
@include mat.app-background();
3

4
:root {
5
  @include mat.elevation-classes(themes.$my-app-theme);
6
  @include mat.app-background(themes.$my-app-theme);
7
}

1.2 Remove individual component themes

1
:root {
2
  @include mat.button-theme(themes.$my-app-theme);
3
  @include mat.icon-theme(themes.$my-app-theme);
4
  @include mat.menu-theme(themes.$my-app-theme);
5
  @include mat.form-field-theme(themes.$my-app-theme);
6
  @include mat.input-theme(themes.$my-app-theme);
7
}

1.3 Changes for typography

Move typography mixin outside of :root and remove usage of themes.$my-app-theme in it.

1
@include mat.typography-hierarchy(
2
  mat.define-theme(
3
    (
4
      typography: (
5
        use-system-variables: true,
6
        system-variables-prefix: mat-sys,
7
      ),
8
    )
9
  )
10
);
11

12
:root {
13
  @include mat.typography-hierarchy(themes.$my-app-theme);
14
}

1.4 Use new theme mixin

1
:root {
2
  @include mat.theme(
3
    (
4
      color: (
5
        primary: mat.$azure-palette,
6
        tertiary: mat.$blue-palette,
7
      ),
8
      typography: Roboto,
9
      density: 0,
10
    )
11
  );
12
}

We will modify the theme colors in next section.

1.5 Remove usage of system-level mixins

1
:root {
2
  @include mat.system-level-colors(themes.$my-app-theme);
3
  @include mat.system-level-typography(themes.$my-app-theme);
4
}

1.6 Changes in button-overrides

As some properties from v18 of button-overrides mixin are deprecated in v19, we need to use the new properties. Replace code of .overrides-example with the following:

1
// Customizing the button appearance using overrides API
2
.overrides-example {
3
  button {
4
    @include mat.button-overrides(
5
      (
6
        filled-container-color: #00ff00,
7
        protected-container-color: #00ff00,
8
        filled-container-height: 64px,
9
        outlined-container-height: 64px,
10
        protected-container-height: 64px,
11
        text-container-height: 64px,
12
        filled-container-shape: 32px,
13
        outlined-container-shape: 32px,
14
        protected-container-shape: 32px,
15
        text-container-shape: 32px,
16
        filled-label-text-color: orange,
17
        outlined-label-text-color: orange,
18
        protected-label-text-color: orange,
19
        text-label-text-color: orange,
20
        filled-ripple-color: #ff0000,
21
        protected-ripple-color: #ff0000,
22
        outlined-ripple-color: #ff0000,
23
        text-ripple-color: #ff0000,
24
        outlined-outline-color: #0000ff,
25
      )
26
    );
27
  }
28
}

2. Updates in dark theme

We will make similar changes in dark theme file at src/styles/themes/dark.scss.

2.1 Remove redundant mixin usages

1
.dark-theme {
2
  @include mat.elevation-classes();
3
  @include mat.app-background();
4
}

2.2 Remove individual component colors

1
.dark-theme {
2
  @include mat.button-color(themes.$my-app-dark-theme);
3
  @include mat.icon-color(themes.$my-app-dark-theme);
4
  @include mat.menu-color(themes.$my-app-dark-theme);
5
  @include mat.form-field-color(themes.$my-app-dark-theme);
6
  @include mat.input-color(themes.$my-app-dark-theme);
7
}

2.3 Use color-scheme

1
.dark-theme {
2
  color-scheme: dark;
3
}

2.4 Remove usage of system-level mixins

1
.dark-theme {
2
  @include mat.system-level-colors(themes.$my-app-dark-theme);
3
  @include mat.system-level-typography(themes.$my-app-dark-theme);
4
}

3. Custom component style changes

3.1 Changes in component styles barrel file

Let’s clean up the barrel file at src/styles/components/_index.scss and keep only single line:

1
@forward "../../app/shared/components/alert/alert-theme.css";

3.2 Remove usage of theme mixin

Remove usage of components.theme mixin from src/styles.scss and src/styles/themes/dark.scss files.

3.3 Using correct tokens

Simply find --sys and replace it with --mat-sys in whole project.

4. Changes for custom theme

We will make changes in src/styles/themes/_custom-theme.scss file.

4.1 Remove usage of define-theme function

1
$custom-theme: mat.define-theme(
2
  (
3
    color: (
4
      primary: mat.$rose-palette,
5
      tertiary: mat.$red-palette,
6
      use-system-variables: false,
7
    ),
8
    typography: (
9
      plain-family: sans-serif,
10
      brand-family: monospace,
11
      use-system-variables: false,
12
    ),
13
    density: (
14
      scale: -3,
15
    ),
16
  )
17
);

4.2 Remove component themes

1
.custom-theme {
2
  @include mat.button-color($custom-theme);
3
  @include mat.button-typography($custom-theme);
4
  @include mat.button-density($custom-theme);
5
}

4.3 Use new theme mixin

1
.custom-theme {
2
  @include mat.theme(
3
    (
4
      color: (
5
        primary: mat.$rose-palette,
6
        tertiary: mat.$red-palette,
7
      ),
8
      typography: (
9
        plain-family: sans-serif,
10
        brand-family: monospace,
11
      ),
12
      density: -3,
13
    )
14
  );
15
}

5. Remove usage of M3 theme file

We want to remove usage of m3-theme.scss file.

Delete m3-theme.scss file.
Delete src/styles/themes/_all.scss file.

6. Create and use new palette file

6.1 Create new palette file

We will create new palette file at src/styles/themes/.

ng generate @angular/material:theme-color --primary-color 6750a4 --directory src/styles/themes/ --interactive false

6.2 Use new palette file

We will use this palette in src/styles.scss file.

1
@use "./styles/themes/theme-colors";
2

3
:root {
4
  @include mat.theme(
5
    (
6
      color: (
7
        primary: mat.$azure-palette,
8
        primary: theme-colors.$primary-palette,
9
        tertiary: mat.$blue-palette,
10
        tertiary: theme-colors.$tertiary-palette,
11
      ),
12
      typography: Roboto,
13
      density: 0,
14
    )
15
  );
16
}

6.2.1 Changes for button color variants

For button color variants, we need to remove usage of button-color mixin and use theme-overrides mixin instead. Note that buttons in Angular Material relies heavily on primary color, so we need to simply override it.

1
@each $variant in $color-variants {
2
  .mat-#{$variant} {
3
    @include mat.button-color(themes.$my-app-theme, $color-variant: $variant);
4
    @include mat.theme-overrides(
5
      (
6
        primary: var(--mat-sys-#{$variant}),
7
        on-primary: var(--mat-sys-on-#{$variant}),
8
      )
9
    );
10
  }
11
}

Changes for color picker

If you change the color from color picker, you will see that the colors are not updated on the UI. This is because the color picker generates CSS variables with --sys prefix, but we are using --mat-sys prefix in our project.

We need to update the color picker to use --mat-sys prefix. Simply add below at the end of generateDynamicTheme function in src/app/shared/components/color-picker/color-picker.component.ts:

1
generateDynamicTheme(isDark?: boolean) {
2
    // rest remains same
3

4
    const styles = targetElement.style;
5
    for (const key in styles) {
6
      if (Object.prototype.hasOwnProperty.call(styles, key)) {
7
        const propName = styles[key];
8
        if (propName.indexOf('--md-sys') === 0) {
9
          const sysPropName =
10
            '--mat-sys' + propName.replace('--md-sys-color', '');
11
          targetElement.style.setProperty(
12
            sysPropName,
13
            targetElement.style.getPropertyValue(propName)
14
          );
15
        }
16
      }
17
    }
18
  }

Changes for density

As of Angular Material 19.1, there is no API available from which we can get density. So, we need to manually pass the density value to alert component.

Let’s clean up src/app/shared/components/alert/_alert-theme.scss file, and keep only below content:

1
@use "sass:map";
2
@use "@angular/material" as mat;
3

4
@mixin density($density) {
5
  $spacing: (
6
    0: 16px,
7
    -1: 12px,
8
    -2: 10px,
9
    -3: 8px,
10
    -4: 6px,
11
    -5: 4px,
12
  );
13
  $scale-spacing: map.get($spacing, $density);
14
  .alert {
15
    padding: $scale-spacing;
16
    margin-bottom: $scale-spacing;
17

18
    hr {
19
      margin: $scale-spacing 0;
20
    }
21
  }
22
}

Next, add forward this file from src/styles/components/_index.scss file.

1
@forward "../../app/shared/components/alert/alert-theme.css";
2
@forward "../../app/shared/components/alert/alert-theme" as alert-theme-*;

Lastly, go to main styles file at src/styles.scss and update the code include alert-theme-density mixin.

1
// rest remains same
2

3
:root {
4
  $density: 0;
5
  @include mat.theme(
6
    (
7
      color: (
8
        primary: theme-colors.$primary-palette,
9
        tertiary: theme-colors.$tertiary-palette,
10
      ),
11
      typography: Roboto,
12
      density: 0,
13
      density: $density,
14
    )
15
  );
16

17
  @include components.alert-theme-density($density);
18
}

Summary of changes for Angular Material Theming API

#	Old API	New API
1	`mat.define-theme` function	`mat.theme` mixin
2	`mat.get-theme-color` function	`--mat-sys-<color>` system variable
2.1 (Example)	`color: mat.get-theme-color($theme, primary);`	`color: var(--mat-sys-primary);`
2.2 (Example)	`color: mat.get-theme-color($theme, on-primary-container);`	`color: var(--mat-sys-on-primary-container);`
3	`mat.get-theme-typography` function	`--mat-sys-<level>-<size>-<token>` system variable
3.1 (Example)	`font: mat.get-theme-typography($theme, "display-large");`	`font: var(--mat-sys-display-large);`
3.2 (Example)	`letter-spacing: mat.get-theme-typography($theme, "body-medium", "letter-spacing");`	`letter-spacing: var(--mat-sys-body-medium-tracking);`
4	`mat.get-theme-density` function	No equivalent new API, manually pass density
5	`mat.typography-hierarchy` mixin	Still available in new API, but not recommended to use. Instead, manually use typography system variables.