Using Theme Styles & Customizing Tokens

System Variables

Angular Material components depend on system variables defined as CSS variables through the mat.theme Sass mixin. That means, we can use the CSS variables defined by mat.theme to apply Angular Material theme’s colors and typography to our application.

The color variables are useful for emphasizing important text and actions, providing stronger application branding, and ensuring strong contrast ratios between surface and on-surface elements.

The typography variables are useful for creating clear information hierarchy and text consistency through the application.

The following example styles demonstrate a component using the color and typography variables to create an application-wide banner presenting important information to the user:

1
:host {
2
  background: var(--mat-sys-primary-container);
3
  color: var(--mat-sys-on-primary-container);
4
  border: 1px solid var(--mat-sys-outline-variant);
5
  font: var(--mat-sys-body-large);
6
}

Colors

Material Design uses color to create accessible, personal color schemes that communicate your product’s hierarchy, state, and brand. See Material Design’s Color System page to learn more about its use and purpose.

General concepts

Here are helpful-to-know words you’ll see in the names of color roles:

• Surface - A role used for backgrounds and large, low-emphasis areas of the screen.
• Primary, Secondary, Tertiary - Accent color roles used to emphasize or de-emphasize foreground elements.
• Container - Roles used as a fill color for foreground elements like buttons. They should not be used for text or icons.
• On - Roles starting with this term indicate a color for text or icons on top of its paired parent color. For example, on primary is used for text and icons against the primary fill color.
• Variant - Roles ending with this term offer a lower emphasis alternative to its non-variant pair. For example, outline variant is a less emphasized version of the outline color.

The following color roles are the most often used in Angular Material components. Use these colors and follow their uses to add theme colors to your application’s custom components.

Primary

Use primary roles for the most prominent components across the UI, such as the FAB, high-emphasis buttons, and active states.

Surface

Use surface roles for more neutral backgrounds, and container colors for components like cards, sheets, and dialogs.

The following colors should be used for backgrounds and large, low-emphasis areas of the screen.

Containers filled with a surface color should apply the --mat-sys-on-surface color to text and icons placed within.

Error

Use error roles to communicate error states, such as an incorrect password entered into a text field.

Outline

There are two outline colors to be used against surface:

Secondary

Use secondary roles for less prominent components in the UI such as filter chips. These colors are less commonly used in Angular Material, but are available for adding color variety and creating additional emphasis to components.

Tertiary

Use tertiary roles for contrasting accents that balance primary and secondary colors or bring heightened attention to an element such as an input field. These colors are less commonly used in Angular Material, but are available for adding color variety and creating additional emphasis to components.

Fixed and on-fixed accent colors

These colors are the same for both light and dark themes. They are unused by any Angular Material components.

Typography

There are five categories of font types defined by Material Design. Learn more about how these categories and their sizes should be used in your application by visiting Material Design’s Typography documentation.

Typescale levels

1. display
2. headline
3. title
4. body
5. label

Each typescale level has three sizes:

1. large
2. medium
3. small

Binding typescale level to native HTML elements

By default, Angular Material does not bind any of the typescale levels to any native HTML elements. But, below is the list of typescale levels those can be used to bind to native HTML elements.

Below is the list of all typography variables defined by Angular Material. Each system variable can be applied to the font CSS style.

Body

Body styles are used for longer passages of text in your app.

Display

As the largest text on the screen, display styles are reserved for short, important text or numerals. They work best on large screens.

Headline

Headlines are best-suited for short, high-emphasis text on smaller screens. These styles can be good for marking primary passages of text or important regions of content.

Label

Label styles are smaller, utilitarian styles, used for things like the text inside components or for very small text in the content body, such as captions.

Buttons, for example, use the label large style.

Title

Titles are smaller than headline styles, and should be used for medium-emphasis text that remains relatively short. For example, consider using title styles to divide secondary passages of text or secondary regions of content.

Accessing the parts of the variable definition

Additionally, the parts of the variable definition can be accessed individually by appending the keywords font, line-height, size, tracking, and weight.

To get the needed CSS variable, you can keep 3 things in mind and it will help you get the correct CSS variable:

1. Pre-typescale levels
   1. display
   2. headline
   3. title
   4. body
   5. label
2. Variations
   1. large
   2. medium
   3. small
3. Properties
   1. font (The CSS font shorthand, includes all font properties except letter-spacing) - No token
   2. font-family - font
   3. font-size - size
   4. font-weight - weight
   5. line-height - line-height
   6. letter-spacing - tracking

--mat-sys-* variables are available for each of the above typescale, which you can use to read or modify the typescale.

Now, just use below format to get the correct CSS variable:

1
.some-class {
2
  some-property: var(
3
    --mat-sys-<pre_typescale_level>-<variation>-<property_token>
4
  );
5
}

So, for example, to get font of display-large, you would write CSS like below:

1
.display-large-clone {
2
  font: var(--mat-sys-display-large);
3

4
  /* As --sys-display-large-font does not include letter-spacing, make sure to include that, too */
5
  letter-spacing: var(--mat-sys-display-large-tracking);
6
}

One more example, to get font-weight of headline of small size, you will write CSS like below:

1
.headline-small-font-weight {
2
  font-weight: var(--mat-sys-headline-small-weight);
3
}

One more example, the values for medium body text may be defined as follows:

1
--mat-sys-body-medium: 400 0.875rem / 1.25rem Roboto, sans-serif;
2
--mat-sys-body-medium-font: Roboto, sans-serif;
3
--mat-sys-body-medium-line-height: 1.25rem;
4
--mat-sys-body-medium-size: 0.875rem;
5
--mat-sys-body-medium-tracking: 0.016rem;
6
--mat-sys-body-medium-weight: 400;

Toolbar Colors

Let’s modify color and background color of the toolbar.

1
.mat-toolbar {
2
  background-color: var(--mat-sys-primary-container);
3
  color: var(--mat-sys-on-primary-container);
4
}

Theme Toggle Border Color

To make theme toggle border color more visible, let’s modify the outline color of the theme toggle.

1
:host {
2
  outline: 1px solid #dee2e6;
3
  outline: 1px solid var(--mat-sys-outline);
4
}

Application Colors

Let’s change the text and other colors of the application to match the theme.

1
.due-date {
2
  color: rgba(0, 0, 0, 0.7);
3
  color: color-mix(in srgb, var(--mat-sys-on-surface), transparent 30%);
4
}
5

6
.todo-card {
7
  &.cdk-drag-preview {
8
    box-shadow:
9
      0 5px 5px -3px rgba(0, 0, 0, 0.2),
10
      0 8px 10px 1px rgba(0, 0, 0, 0.14),
11
      0 3px 14px 2px rgba(0, 0, 0, 0.12);
12
    box-shadow:
13
      0 5px 5px -3px color-mix(in srgb, var(--mat-sys-shadow), transparent 80%),
14
      0 8px 10px 1px color-mix(in srgb, var(--mat-sys-shadow), transparent 86%),
15
      0 3px 14px 2px color-mix(in srgb, var(--mat-sys-shadow), transparent 88%);
16
  }
17
}

1
.empty-state {
2
  color: rgba(0, 0, 0, 0.6);
3
  color: color-mix(in srgb, var(--mat-sys-on-surface), transparent 40%);
4
}
5

6
.completed-header {
7
  color: rgba(0, 0, 0, 0.6);
8
  color: color-mix(in srgb, var(--mat-sys-on-surface), transparent 40%);
9
  border-top: 1px solid rgba(0, 0, 0, 0.12);
10
  border-top: 1px solid
11
    color-mix(in srgb, var(--mat-sys-outline), transparent 88%);
12
}

Application Typography

Let’s use Angular Material’s typography to style the no todos text.

1
.empty-state {
2
  h2 {
3
    font: var(--mat-sys-display-small);
4
    letter-spacing: var(--mat-sys-display-small-tracking);
5
  }
6

7
  p {
8
    font: var(--mat-sys-title-small);
9
    letter-spacing: var(--mat-sys-title-small-tracking);
10
  }
11
}

And also completed header text.

1
.completed-header {
2
  // rest remains same
3
  font: var(--mat-sys-title-small);
4
  letter-spacing: var(--mat-sys-title-small-tracking);
5
}

Customizing Tokens

Angular Material components also allow for narrowly targeted customization of specific tokens through the overrides mixins. This enables fine-grained adjustments to specific system-level theme CSS variables as well as individual component tokens, such as a component’s border-color or title font size.

The overrides API validates that the customized tokens are correctly spelled and can be used to ensure backwards compatibility if tokens are added, moved, or renamed in future versions.

System Tokens

System-level tokens can be changed to different values through the mat.theme-overrides mixin, which will redefine CSS variables that are used in the application.

The following example applies a violet color palette for the application, but alters the primary-container token to a specific shade of blue.

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

3
html {
4
  color-scheme: light dark;
5
  @include mat.theme(
6
    (
7
      color: mat.$violet-palette,
8
      typography: Roboto,
9
      density: 0,
10
    )
11
  );
12

13
  .example-orange-primary-container {
14
    @include mat.theme-overrides(
15
      (
16
        primary-container: #84ffff,
17
      )
18
    );
19
  }
20
}

Alternatively, an optional override map can be provided in the mat.theme mixin to replace values applied by the mixin:

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

3
html {
4
  color-scheme: light dark;
5
  @include mat.theme((
6
    color: mat.$violet-palette,
7
    typography: Roboto,
8
    density: 0
9
  ), $overrides: (
10
    primary-container: orange,
11
  );
12
}

Component Tokens

Each Angular Material component defines an overrides mixin that can be used to customize tokenized styles for their color, typography, and density.

More information for each component’s override API, including their list of available customizable tokens, can be found on their respective documentation page under the Styling tab.

The following example demonstrates the Card’s overrides API to change the background color to red, increase the corner border radius, and specify a larger title font size.

1
html {
2
  @include mat.card-overrides(
3
    (
4
      elevated-container-color: red,
5
      elevated-container-shape: 32px,
6
      title-text-size: 2rem,
7
    )
8
  );
9
}

When to use what?

With lot of mixins for theming overrides and customizations it can become confusing to decide when to use which so I will try to summarize which mixin to use in which scenario.

Add Todo Button Overrides

We will use the mat.fab-overrides mixin to change the tokens of the add todo button.

1
@use "@angular/material" as mat;
2
.add-todo-fab {
3
  // rest remains same
4
  @include mat.fab-overrides(
5
    (
6
      container-shape: 100%,
7
      container-color: var(--mat-sys-tertiary-container),
8
      foreground-color: var(--mat-sys-on-tertiary-container),
9
      state-layer-color: var(--mat-sys-on-tertiary-container),
10
    )
11
  );
12
}

Todo Card Component

Let’s modify colors of priority chips in todo cards.

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

3
// rest remains same
4

5
$priority-colors: (
6
  low: (
7
    outline-color: var(--mat-sys-primary),
8
    background: var(--mat-sys-surface-container),
9
    foreground: var(--mat-sys-on-surface-container),
10
  ),
11
  medium: (
12
    outline-color: var(--mat-sys-secondary),
13
    background: var(--mat-sys-secondary-container),
14
    foreground: var(--mat-sys-on-secondary-container),
15
  ),
16
  high: (
17
    outline-color: var(--mat-sys-error),
18
    background: var(--mat-sys-error-container),
19
    foreground: var(--mat-sys-on-error-container),
20
  ),
21
);
22

23
@each $priority, $colors in $priority-colors {
24
  .priority-chip.priority-#{$priority} {
25
    background-color: map-get($colors, background);
26
    @include mat.chips-overrides(
27
      (
28
        outline-color: map-get($colors, outline-color),
29
        label-text-color: map-get($colors, foreground),
30
      )
31
    );
32
  }
33
}

Then modify the class of the priority chip to apply the overrides in file src/app/components/todo-list-section/todo-list-section.component.html

1
<mat-chip class="priority-chip">
2
<mat-chip [class]="'priority-chip priority-' + todo.priority">
3
  {{ todo.priority }}
4
</mat-chip>