Dimension: Color

Pre-built theme

Angular Material includes several pre-built theme CSS files, each with different palettes selected. You can use one of these pre-built themes if you don’t want to define a custom theme with Sass.

How to use pre-built theme

There are 2 ways to use pre-built themes:

1. Through schematic - when you run ng add @angular/material, select the theme you want.
2. Through manually importing CSS file

When we installed Angular Material, we selected Custom in theme selection. If you want any pre-built theme, you can select any theme instead of Custom. There are 4 pre-built themes provided:

For instance, if you want to use azure-blue’s theme, you just need to include that file in the styles array of your project’s angular.json file:

"styles": [
    "@angular/material/prebuilt-themes/azure-blue.css",
    // other styles
],

Custom theme

A theme file is a SASS file that uses Angular Material SASS mixins to produce color and typography CSS styles.

Let’s jump to src/styles.scss file and have a look at our theme:

1
@use "@angular/material" as mat;
2

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

17
html,
18
body {
19
  height: 100%;
20
}
21
body {
22
  margin: 0;
23
  font-family: Roboto, "Helvetica Neue", sans-serif;
24
}

Defining a theme

Angular Material represents a theme as a SASS map that contains your color, typography and density choices, as well as some base design system settings.

The mat.theme mixin

The mat.theme mixin takes a map that defines color, typography, and density values and outputs a set of CSS variables that control the component appearance and layout. These variables are based on Design Tokens.

The color variables are defined using the CSS color function light-dark so that your theme can switch between light and dark mode using the CSS property color-scheme.

The theme file in our application applies a azure and blue colors for primary and tertiary palettes, Roboto font, and standard density to the application’s Angular Material components. It targets the html selector to ensure the CSS variables are applied across the entire application.

The configuration object may have the following properties.

Each property is nothing but a dimension in Angular Material theming. For this chapter, we will focus on color property.

Color

The theme’s color determines the component color styles, such as the fill color of checkboxes or ripple color of buttons. It depends on color palettes of varying tones to build a color scheme. Check out the Palettes section to learn about available prebuilt palettes, or how to create custom palettes.

You can set the color in one of two ways: as a single color palette, or as a color map.

Single Color Palette

If you provide a single color palette, Angular Material uses its values for the theme’s primary, secondary, and tertiary colors. The CSS color values will be defined using light-dark CSS color function. Your application styles should define an explicit value declaration for the color-scheme CSS property.

A single color palette can be defined as below:

1
html {
2
  @include mat.theme(
3
    (
4
      color: mat.$azure-palette,
5
    )
6
  );
7
}

Color Map

If you provide a color map, then the tertiary color palette can be configured separately from the primary palette. The tertiary palette can be used to add a distinct accent color to some components.

You can also set the theme-type to determine the colors. theme-type can be one of the following:

• color-scheme - include both light and dark colors using the light-dark CSS color function
• light - only define the light color values
• dark - only define the dark color values

A color map can be defined as below:

1
html {
2
  @include mat.theme(
3
    (
4
      color: (
5
        theme-type: light,
6
        primary: mat.$azure-palette,
7
        tertiary: mat.$blue-palette,
8
      )
9
    )
10
  );
11
}

Color Palettes

A color palette is a set of similar colors with different hues ranging from light to dark. The Angular Material theme uses color palettes to create a color scheme to communicate an application’s hierarchy, state, and brand.

Let’s understand how a palette is structured, which are used for primary and tertiary properties as mentioned above.

Palette’s structure

A palette is a map of below properties:

To understand more about these properties take a look at Material 3 Color roles.

Palette HCT Tonal Values

Each property of a palette is a map, which should have a valid CSS color associated with each of these keys, these are also referred as HCT Tonal Values: 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100 for all, plus 4, 6, 12, 17, 22, 24, 87, 92, 94, 96 extra colors for neutral.

For example, take a look at below map of $azure-palette:

1
$azure-palette: (
2
  0: #000000,
3
  10: #001b3f,
4
  20: #002f65,
5
  25: #003a7a,
6
  30: #00458f,
7
  35: #0050a5,
8
  40: #005cbb,
9
  50: #0074e9,
10
  60: #438fff,
11
  70: #7cabff,
12
  80: #abc7ff,
13
  90: #d7e3ff,
14
  95: #ecf0ff,
15
  98: #f9f9ff,
16
  99: #fdfbff,
17
  100: #ffffff,
18
  secondary: (
19
    // Colors map for the range 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100
20
  ),
21
  tertiary: (
22
    // Colors map for the range 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100
23
  ),
24
  neutral: (
25
    // Colors map for the range 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100
26
     // plus additional colors for 4, 6, 12, 17, 22, 24, 87, 92, 94, 96
27
  ),
28
  neutral-variant: (
29
    // Colors map for the range 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100
30
  ),
31
  error: (
32
    // Colors map for the range 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100
33
  ),
34
);

Theme Color Property vs Palette Map Property

It can be confusing having primary and tertiary at two places: theme configuration and palette property.

1. primary/tertiary in theme configuration refers to the color roles
2. primary/tertiary properties in palettes help define the whole color role.

Theme Configuration for different inputs

Let’s understand how the final theme will look like for different inputs to mat.theme mixin.

For any input, the final theme is constructed like below:

Input 1: Not providing color property

When you don’t provide color property in theme configuration object, it will not generate CSS variables for color.

1
html {
2
  @include mat.theme();
3
}

Input 2: Not providing any palettes

When neither primary nor tertiary palettes are assigned in theme configuration object, it will take default values.

1
html {
2
  @include mat.theme(
3
    (
4
      color: (),
5
    )
6
  );
7
}

Final theme looks like below:

You can view the theme in action on Theme Builder for Angular Material.

Input 2: Providing only primary palette

When you provide only primary palette, Angular Material will use same for tertiary too:

1
html {
2
  @include mat.theme(
3
    (
4
      color: (
5
        primary: mat.$azure-palette,
6
      ),
7
    )
8
  );
9
}

Final theme looks like below:

You can view the theme in action on Theme Builder for Angular Material.

Input 3: Providing both primary and tertiary palette

1
html {
2
  @include mat.theme(
3
    (
4
      color: (
5
        primary: mat.$azure-palette,
6
        tertiary: mat.$blue-palette,
7
      ),
8
    )
9
  );
10
}

Final theme looks like below:

You can view the theme in action on Theme Builder for Angular Material.

Summary

To summarize, below is how whole theme is constructed:

1. You pass theme palettes for primary and tertiary
2. A palette should contain these color roles: primary, secondary, tertiary (optional), neutral, neutral-variant, error
3. Each color role should contain valid CSS color values for the range 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99, 100, plus 4, 6, 12, 17, 22, 24, 87, 92, 94, 96 extra colors for neutral.

For example, one could create a custom palette for golden brown (#B17F32) color like below:

1
$golden-brown-palette: (
2
  primary: (
3
    0: #000000,
4
    10: #291800,
5
    20: #452b00,
6
    25: #533500,
7
    30: #624000,
8
    35: #724a00,
9
    40: #815606,
10
    50: #9d6e22,
11
    60: #ba8739,
12
    70: #d8a151,
13
    80: #f6bc69,
14
    90: #ffddb3,
15
    95: #ffeedc,
16
    98: #fff8f4,
17
    99: #fffbff,
18
    100: #ffffff,
19
  ),
20
  secondary: (
21
    0: #000000,
22
    10: #291801,
23
    20: #402d10,
24
    25: #4c381a,
25
    30: #584324,
26
    35: #654e2f,
27
    40: #725a3a,
28
    50: #8d7350,
29
    60: #a88c68,
30
    70: #c4a680,
31
    80: #e1c29a,
32
    90: #feddb4,
33
    95: #ffeedc,
34
    98: #fff8f4,
35
    99: #fffbff,
36
    100: #ffffff,
37
  ),
38
  tertiary: (
39
    0: #000000,
40
    10: #191e00,
41
    20: #2c3400,
42
    25: #364000,
43
    30: #414c01,
44
    35: #4c580e,
45
    40: #58641a,
46
    50: #717d31,
47
    60: #8a9748,
48
    70: #a5b260,
49
    80: #c0ce78,
50
    90: #dcea91,
51
    95: #eaf99e,
52
    98: #f6ffc0,
53
    99: #fcffdd,
54
    100: #ffffff,
55
  ),
56
  neutral: (
57
    0: #000000,
58
    10: #201b15,
59
    20: #352f29,
60
    25: #403a34,
61
    30: #4c463f,
62
    35: #58514a,
63
    40: #645d56,
64
    50: #7e766e,
65
    60: #988f87,
66
    70: #b3aaa1,
67
    80: #cfc5bb,
68
    90: #ebe1d7,
69
    95: #faefe5,
70
    98: #fff8f4,
71
    99: #fffbff,
72
    100: #ffffff,
73
    4: #120d08,
74
    6: #17130d,
75
    12: #241f19,
76
    17: #2e2923,
77
    22: #3a342d,
78
    24: #3e3832,
79
    87: #e3d8cf,
80
    92: #f1e6dd,
81
    94: #f7ece2,
82
    96: #fdf2e8,
83
  ),
84
  neutral-variant: (
85
    0: #000000,
86
    10: #221a0f,
87
    20: #382f23,
88
    25: #443a2d,
89
    30: #504538,
90
    35: #5c5143,
91
    40: #685c4e,
92
    50: #827566,
93
    60: #9c8e7e,
94
    70: #b8a998,
95
    80: #d4c4b2,
96
    90: #f1e0ce,
97
    95: #ffeedc,
98
    98: #fff8f4,
99
    99: #fffbff,
100
    100: #ffffff,
101
  ),
102
  error: (
103
    0: #000000,
104
    10: #410002,
105
    20: #690005,
106
    25: #7e0007,
107
    30: #93000a,
108
    35: #a80710,
109
    40: #ba1a1a,
110
    50: #de3730,
111
    60: #ff5449,
112
    70: #ff897d,
113
    80: #ffb4ab,
114
    90: #ffdad6,
115
    95: #ffedea,
116
    98: #fff8f7,
117
    99: #fffbff,
118
    100: #ffffff,
119
  ),
120
);

Prebuilt Color Palettes

Angular Material provides twelve prebuilt color palettes that can be used for your application’s theme:

• $red-palette
• $green-palette
• $blue-palette
• $yellow-palette
• $cyan-palette
• $magenta-palette
• $orange-palette
• $chartreuse-palette
• $spring-green-palette
• $azure-palette
• $violet-palette
• $rose-palette

In our application, $azure-palette is used for primary and $blue-palette for tertiary.

Custom Color Palettes

The Angular Material palette generation schematic builds custom color palettes based on a single color input for the primary color, and optionally color inputs to further customize secondary, tertiary, and neutral palettes.

Let’s run the schematic to generate a custom color palette:

ng generate @angular/material:theme-color

After running the above command answer the prompts as below:

Or you can run the schematic without answering any prompts by passing the color value as a parameter:

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

Generated file output

The result of running the schematic is a new file with the generated custom colors. Color palettes get defined in the generated file that you can pass into the theme() mixin in your own theme file. See the Sass themes section for more information.

Sass themes

The output of the schematic will create a file named _theme-colors.scss at the src/styles directory. The exported palettes ($primary-palette and $tertiary-palette) can be provided to the theme mixin within your theme file to use the custom colors.

Let’s import the generated file and use the palettes in our src/styles.scss file:

1
@use "@angular/material" as mat;
2
@use "./styles/theme-colors" as my-app-theme;
3

4
html {
5
  @include mat.theme(
6
    (
7
      color: (
8
        primary: mat.$azure-palette,
9
        primary: my-app-theme.$primary-palette,
10
        tertiary: mat.$blue-palette,
11
        tertiary: my-app-theme.$tertiary-palette,
12
      ),
13
      typography: Roboto,
14
      density: 0,
15
    )
16
  );
17
}
18
// rest remains same

High contrast override mixins

High contrast override theme mixins are also generated in the file because we selected it in the prompts. These mixins override the system level variables with high contrast equivalent values from your theme. This is helpful for users who prefer more contrastful colors for either preference or accessibility reasons.

To show the high contrast values when user’s specify based on their color system preferences, apply the high-contrast-overrides() mixin from the generated file wrapped inside @media (prefers-contrast: more) in your theme file. You can pass in light, dark, or color-scheme. To see the high contrast values in your application locally, you can use Chrome DevTools to emulate the CSS media features.

1
html {
2
  // rest remains same
3

4
  @media (prefers-contrast: more) {
5
    @include my-app-theme.high-contrast-overrides(light);
6
  }
7
}

Supporting Light and Dark Mode

By default, the mat.theme mixin defines colors using the CSS color function light-dark to make it easy for your application to switch between light and dark mode. The light-dark function depends on the value of color-scheme declared in your application’s global styles. If your application does not define a value for color-scheme, then the light colors will always be applied.

You can define color-scheme: light or color-scheme: dark to explicitly define your application’s mode. To set the mode depending on the user’s system preferences, use color-scheme: light-dark. Let’s make that change in our src/styles.scss:

1
html {
2
  color-scheme: light dark;
3

4
  @media (prefers-contrast: more) {
5
    @include my-app-theme.high-contrast-overrides(light);
6
    @include my-app-theme.high-contrast-overrides(color-scheme);
7
  }
8
}

Light and Dark themes based on user preferences

Instead of defining the mode in the theme file, you can define it based on user’s system preferences. We will use the strategy of defining color-scheme under a CSS selector so that the mode depends on whether that class has been applied. In our case, the application should display the light mode theme unless the class .dark-mode is added to the HTML body.

Let’s make that change in our src/styles.scss:

1
html {
2
  color-scheme: light dark;
3
  color-scheme: light;
4
  // rest remains same
5
}
6

7
body.dark-mode {
8
  color-scheme: dark;
9
}

Default background and text colors

We will use the following styles in src/index.html to apply the theme’s surface background and on-surface text colors as a default across the application:

1
<!doctype html>
2
<html lang="en">
3
  <head>
4
    <!-- rest remains same -->
5
    <style>
6
      .app-background {
7
        background: var(--mat-sys-surface);
8
        color: var(--mat-sys-on-surface);
9
      }
10
    </style>
11
  </head>
12
  <body class="mat-typography">
13
  <body class="mat-typography app-background">
14
    <app-root></app-root>
15
  </body>
16
</html>

Theme toggle

To implement theme toggle, we will create a service and a component.

ThemeChangerService

To load the dark-theme based on user’s selection, we will simply implement a service called ThemeChangerService and whenever we want to change theme, we will call changeTheme from this service:

1
import { DOCUMENT } from '@angular/common';
2
import { Injectable, inject, signal, effect } from '@angular/core';
3
import { LocalStorageService } from './local-storage.service';
4

5
const LOCAL_STORAGE_THEME_KEY = 'my-app-theme';
6
export type Theme = 'dark' | 'light' | 'auto';
7
export type ThemeWithoutAuto = Exclude<Theme, 'auto'>;
8
const DARK_MODE_CLASS = 'dark-mode';
9

10
@Injectable({ providedIn: 'root' })
11
export class ThemeChangerService {
12
  private _document = inject(DOCUMENT);
13
  private browserStorage = inject(LocalStorageService);
14
  private _isDark = signal(false);
15
  public isDark = this._isDark.asReadonly();
16
  private _window = this._document.defaultView;
17

18
  constructor() {
19
    this.setTheme(this.getPreferredTheme());
20
    if (this._window !== null && this._window.matchMedia) {
21
      this._window
22
        .matchMedia('(prefers-color-scheme: dark)')
23
        .addEventListener('change', () => {
24
          const storedTheme = this.getStoredTheme();
25
          if (storedTheme !== 'light' && storedTheme !== 'dark') {
26
            this.setTheme(this.getPreferredTheme());
27
          }
28
        });
29
    }
30

31
    effect(() => {
32
      if (this._isDark()) {
33
        this._document.documentElement.classList.add(DARK_MODE_CLASS);
34
        this.setStoredTheme('dark');
35
      } else {
36
        this._document.documentElement.classList.remove(DARK_MODE_CLASS);
37
        this.setStoredTheme('light');
38
      }
39
    });
40
  }
41

42
  private getStoredTheme = () =>
43
    this.browserStorage.load<ThemeWithoutAuto>(LOCAL_STORAGE_THEME_KEY);
44
  private setStoredTheme = (theme: ThemeWithoutAuto) => {
45
    this.browserStorage.save(LOCAL_STORAGE_THEME_KEY, theme);
46
  };
47

48
  private getPreferredTheme = (): Theme => {
49
    const storedTheme = this.getStoredTheme();
50

51
    if (storedTheme) {
52
      return storedTheme;
53
    }
54

55
    if (this._window !== null && this._window.matchMedia) {
56
      return this._window.matchMedia('(prefers-color-scheme: dark)').matches
57
        ? 'dark'
58
        : 'light';
59
    }
60
    return 'light';
61
  };
62

63
  private setTheme = (
64
    theme: Theme,
65
    document = this._document,
66
    isDarkSignal = this._isDark
67
  ) => {
68
    if (document.defaultView !== null && document.defaultView.matchMedia) {
69
      if (
70
        theme === 'auto' &&
71
        document.defaultView.matchMedia('(prefers-color-scheme: dark)').matches
72
      ) {
73
        isDarkSignal.set(true);
74
      } else {
75
        isDarkSignal.set(theme === 'dark');
76
      }
77
    }
78
  };
79

80
  public changeTheme(theme: ThemeWithoutAuto) {
81
    this.setStoredTheme(theme);
82
    this.setTheme(theme);
83
  }
84
}

Codes for both, ThemeManager and BrowserStorage are self-explanatory. Please modify it according to need of your application.

ThemeToggleComponent

Now, we will create a component called ThemeToggleComponent which will be used to toggle the theme:

1
<div class="track [class.is-dark-mode]="isDark()">
2
  <div class="dark-mode switch" role="button" (click)="changeTheme('dark')">
3
    <mat-icon>dark_mode</mat-icon>
4
  </div>
5
  <div class="light-mode switch" role="button" (click)="changeTheme('light')">
6
    <mat-icon>light_mode</mat-icon>
7
  </div>
8
</div>

1
import { Component, inject } from '@angular/core';
2
import {
3
  ThemeChangerService,
4
  ThemeWithoutAuto,
5
} from '../../services/theme-changer.service';
6
import { MatIconModule } from '@angular/material/icon';
7

8
@Component({
9
  selector: 'app-theme-toggle',
10
  standalone: true,
11
  templateUrl: './theme-toggle.component.html',
12
  styleUrls: ['./theme-toggle.component.scss'],
13
  imports: [MatIconModule],
14
})
15
export class ThemeToggleComponent {
16
  private themeChanger = inject(ThemeChangerService);
17
  isDark = this.themeChanger.isDark;
18

19
  changeTheme(theme: ThemeWithoutAuto) {
20
    this.themeChanger.changeTheme(theme);
21
  }
22
}

1
:host {
2
  --size: 36px;
3
  width: var(--size);
4
  height: var(--size);
5
  .switch {
6
    width: var(--size);
7
    height: var(--size);
8
  }
9
}
10

11
:host {
12
  height: var(--size);
13
  transition: background-color 0.3s cubic-bezier(0.2, 0, 0, 1);
14
  border: 2px solid transparent;
15
  border-radius: 32px;
16
  outline: 1px solid #dee2e6;
17
  cursor: pointer;
18
  user-select: none;
19
  overflow: hidden;
20
}
21

22
.track {
23
  transition: transform 0.3s cubic-bezier(0.2, 0, 0, 1);
24
  &.is-dark-mode {
25
    transform: translateY(calc(-1 * var(--size)));
26
  }
27
}
28

29
.switch {
30
  display: flex;
31
  align-items: center;
32
  justify-content: center;
33
}

Next, we will add this component to the AppComponent:

1
<mat-toolbar color="primary">
2
  <span>Todo App</span>
3
  <app-theme-toggle class="theme-toggle"></app-theme-toggle>
4
</mat-toolbar>

1
import { ThemeToggleComponent } from './components/theme-toggle/theme-toggle.component';
2

3
@Component({
4
  // rest remains same
5
  imports: [
6
    // other imports
7
    ThemeToggleComponent,
8
  ],
9
})
10
export class AppComponent { /* ... */ }

1
// rest remains same
2
.mat-toolbar {
3
  // rest remains same
4

5
  .theme-toggle {
6
    margin-left: auto;
7
  }
8
}