DEV Community: Dharmen Shah

How to handle browser storage in Angular SSR?

Dharmen Shah — Sat, 25 Nov 2023 16:33:24 +0000

Server-side applications may not have access to certain browser APIs and features. They are unable to utilize browser-specific global objects such as window, document, navigator, or location, and certain HTMLElement properties.

Typically, code that depends on symbols specific to a browser should be run only in the browser, not on the server. This can be ensured using the lifecycle hooks afterRender and afterNextRender. These hooks are executed only in the browser and are bypassed on the server.

But, in some cases, afterRender or afterNextRender are not helpful. For example, when you want to use localStorage in services.

Let's see how we can handle such scenario in a step-by-step guide.

1. A service to use browser storage for Browser

Let's create a BrowserStorageService with below content:

import { Inject, Injectable, InjectionToken } from '@angular/core';

export const BROWSER_STORAGE = new InjectionToken<Storage>('Browser Storage', {
  providedIn: 'root',
  factory: () => localStorage,
});

@Injectable()
export class BrowserStorageService {
  constructor(@Inject(BROWSER_STORAGE) public storage: Storage) {}

  get(key: string) {
    return this.storage.getItem(key);
  }

  set(key: string, value: string) {
    this.storage.setItem(key, value);
  }

  remove(key: string) {
    this.storage.removeItem(key);
  }

  clear() {
    this.storage.clear();
  }
}

As you can see, we have created a service to handle browser storage.

2. Provide service to whole browser application

Now, add BrowserStorageService in providers array of your app.config.ts if you are using standalone mode or in app.module.ts if you are using module mode.

providers: [BrowserStorageService],

Now, instead of using localStorage directly, use BrowserStorageService everywhere in your whole application.

Please note that we have not yet handled the server-side implementation. If you try to build the project, you will get error similar to below:

ERROR ReferenceError: localStorage is not defined

Let's fix that.

3. A service to use browser storage for Server

Now, server don't have any global variables like localStorage and hence it fails when it runs the application with BrowserStorageService

The idea is to provide an implementation to server-side code, so that it works without breaking.

Let's create another service called BrowserStorageServerService with below content:

import { Injectable } from '@angular/core';
import { BrowserStorageService } from './browser-storage.service';

@Injectable()
export class BrowserStorageServerService extends BrowserStorageService {
  constructor() {
    super({
      clear: () => {},
      getItem: (key: string) => JSON.stringify({ key }),
      setItem: (key: string, value: string) => JSON.stringify({ [key]: value }),
      key: (index: number) => index.toString(),
      length: 0,
      removeItem: (key: string) => JSON.stringify({ key }),
    });
  }
}

As you can see, we have extended BrowserStorageServerService from BrowserStorageService, so that we can easily override the methods.

This is just a mock service, it's important to have all the methods in place, implementation doesn't matter, you can change as you like.

4. Provide service to whole server application

Now, we will have to tell server to use BrowserStorageServerService whenever it gets instance of BrowserStorageService. It can be easily done by provide and useClass properties of ClassProvider.

Update the providers array of your app.config.server.ts if you are using standalone mode or in app.server.module.ts if you are using module mode:

providers: [
    {
      provide: BrowserStorageService,
      useClass: BrowserStorageServerService,
    },
  ],

Thats it! Now your application should run fine.

Practical guide for loading SVG icons with Angular Material

Dharmen Shah — Fri, 24 Nov 2023 14:21:40 +0000

mat-icon makes it easier to use vector-based icons in your app. This directive supports both icon fonts and SVG icons, but not bitmap-based formats (png, jpg, etc.).

In this guide, we will learn how to use SVG icons with mat-icon. We will look at all the methods provided by MatIconRegistry and how to practically use each.

Before moving ahead, make sure to either import HttpClientModule or use provideHttpClient from the @angular/common/http package in your NgModule imports or ApplicationConfig providers.

`MatIconRegistry`

MatIconRegistry is a service to register and display icons used by the <mat-icon> component. It helps to:

Register icon URLs by namespace and name
Register icon set URLs by namespace
Register aliases for CSS classes, for use with icon fonts.
Loads icons from URLs and extracts individual icons from icon sets.

Let's look at all of it's methods and a code snippet for each to explain it's practical usage.

`addSvgIcon`

This method registers an icon by URL in the default namespace.

@Component({
  template: `
      <mat-icon
        svgIcon="face"
        aria-hidden="false"
        aria-label="Example face SVG icon"
      ></mat-icon>
  `,
})
export class AppComponent {
  constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) {
    iconRegistry.addSvgIcon(
      "face",
      sanitizer.bypassSecurityTrustResourceUrl("/assets/icons/face.svg")
    );
  }
}

`addSvgIconInNamespace`

This method registers an icon by URL in the specified namespace.

This is same as addSvgIcon, but you can assign the icon to a namespace. For example, if your namespace is app, you would use the icon like below:

<mat-icon
    svgIcon="app:face"
    aria-hidden="false"
    aria-label="Example settings SVG icon"
></mat-icon>

`addSvgIconLiteral`

This method registers an icon using an HTML string in the default namespace.

const THUMBUP_ICON =
  `
  <svg xmlns="http://www.w3.org/2000/svg" width="24px" height="24px">
    <path d="M0 0h24v24H0z" fill="none"/>
    <path d="M1 21h4V9H1v12zm22-11c0-1.1-.9-2-2-2h-6.31l.95-4.57.03-.32c0-.41-.17-.79-.` +
  `44-1.06L14.17 1 7.59 7.59C7.22 7.95 7 8.45 7 9v10c0 1.1.9 2 2 2h9c.83 0 1.54-.5` +
  `1.84-1.22l3.02-7.05c.09-.23.14-.47.14-.73v-1.91l-.01-.01L23 10z"/>
  </svg>
`;
@Component({
  template: `
      <mat-icon
      svgIcon="thumbs-up"
      aria-hidden="false"
      aria-label="Example thumbs-up SVG icon"
    ></mat-icon>
  `,
})
export class AppComponent {
  constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) {
    iconRegistry.addSvgIconLiteral(
      "thumbs-up",
      sanitizer.bypassSecurityTrustHtml(THUMBUP_ICON)
    );
  }
}

`addSvgIconLiteralInNamespace`

This method registers an icon using an HTML string in the specified namespace.

This is same as addSvgIcon, but you can assign the icon to a namespace. For example, if your namespace is app, you would use the icon like below:

<mat-icon
    svgIcon="app:thumbs-up"
    aria-hidden="false"
    aria-label="Example thumbs-up SVG icon"
></mat-icon>

`addSvgIconResolver`

This method registers an icon resolver function with the registry. The function will be invoked with the name and namespace of an icon when the registry tries to resolve the URL from which to fetch the icon. The resolver is expected to return a SafeResourceUrl that points to the icon, an object with the icon URL and icon options, or null if the icon is not supported. Resolvers will be invoked in the order in which they have been registered.

Use this method when you want to dynamically load icons from a single folder. For example, below can be location of your icons:

src/assets/icons/done.svg
src/assets/icons/favorite.svg

@Component({
  template: `
      <mat-icon
        svgIcon="done"
        aria-hidden="false"
        aria-label="Example done SVG icon"
      ></mat-icon>
      <mat-icon
        svgIcon="favorite"
        aria-hidden="false"
        aria-label="Example favorite SVG icon"
      ></mat-icon>
  `,
})
export class AppComponent {
  constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) {
    const resolver: IconResolver = (name) =>
      sanitizer.bypassSecurityTrustResourceUrl(`/assets/icons/${name}.svg`);
    iconRegistry.addSvgIconResolver(resolver);
  }
}

In above code, note the usage of resolver function. It accepts an argument of icon name, which is passed through addSvgIconResolver.

`addSvgIconSet`

This method registers an icon set by URL in the default namespace.

Use this method when you have all icons present in a single SVG sprite file.

Assuming that you have an SVG sprite file present at src/assets/icons-sprite.svg with below content:

<svg xmlns="http://www.w3.org/2000/svg">
    <symbol id="search" height="24" viewBox="0 -960 960 960" width="24">
        <path
            d="M784-120 532-372q-30 24-69 38t-83 14q-109 0-184.5-75.5T120-580q0-109 75.5-184.5T380-840q109 0 184.5 75.5T640-580q0 44-14 83t-38 69l252 252-56 56ZM380-400q75 0 127.5-52.5T560-580q0-75-52.5-127.5T380-760q-75 0-127.5 52.5T200-580q0 75 52.5 127.5T380-400Z" />
    </symbol>
    <symbol id="settings" height="24" viewBox="0 -960 960 960" width="24">
        <path
            d="m370-80-16-128q-13-5-24.5-12T307-235l-119 50L78-375l103-78q-1-7-1-13.5v-27q0-6.5 1-13.5L78-585l110-190 119 50q11-8 23-15t24-12l16-128h220l16 128q13 5 24.5 12t22.5 15l119-50 110 190-103 78q1 7 1 13.5v27q0 6.5-2 13.5l103 78-110 190-118-50q-11 8-23 15t-24 12L590-80H370Zm70-80h79l14-106q31-8 57.5-23.5T639-327l99 41 39-68-86-65q5-14 7-29.5t2-31.5q0-16-2-31.5t-7-29.5l86-65-39-68-99 42q-22-23-48.5-38.5T533-694l-13-106h-79l-14 106q-31 8-57.5 23.5T321-633l-99-41-39 68 86 64q-5 15-7 30t-2 32q0 16 2 31t7 30l-86 65 39 68 99-42q22 23 48.5 38.5T427-266l13 106Zm42-180q58 0 99-41t41-99q0-58-41-99t-99-41q-59 0-99.5 41T342-480q0 58 40.5 99t99.5 41Zm-2-140Z" />
    </symbol>
</svg>

@Component({
  template: `
      <mat-icon
        svgIcon="search"
        aria-hidden="false"
        aria-label="Example search SVG icon"
      ></mat-icon>
      <mat-icon
        svgIcon="settings"
        aria-hidden="false"
        aria-label="Example settings SVG icon"
      ></mat-icon>
  `,
})
export class AppComponent {
  constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) {
    iconRegistry.addSvgIconSet(
      sanitizer.bypassSecurityTrustResourceUrl("/assets/icons-sprite.svg")
    );
  }
}

Summary

Below are list of all MatIconRegistry methods related to load SVGs in mat-icon.

#	Methods	Use when
1	`addSvgIcon`, `addSvgIconInNamespace`	Each icon has separate SVG file
2	`addSvgIconLiteral`, `addSvgIconLiteralInNamespace`	Each icon has SVG string literals, for example, icon string is coming from server
3	`addSvgIconResolver`	Individual icon's SVG files' location share same logic, for example, they are located under one folder
4	`addSvgIconSet`, `addSvgIconSetInNamespace`	All icons are present in same SVG sprite file
5	`addSvgIconSetLiteral`, `addSvgIconSetLiteralInNamespace`	All icons are present in same SVG sprite and sprite is stored as string, for example, coming from server

Live Playground

Code is available on GitHub at Angular-Material-Dev/article-mat-icon-svg

stackblitz.com

Create size variant for Angular Material Button

Dharmen Shah — Wed, 22 Nov 2023 11:12:15 +0000

How to change size

To make size changes work accurately, we need to handle the size of all inner components (like ripple, label, touch area, etc.) respectfully for a mat-button in our example.

Angular Material library provides an easy way to do it. Its called density.

Density

Density mixins includes styles related to the size and spacing of elements in your application. These style should be included at least once in your application.

In Angular Material, Density can have maximum value as 0 and minimum value as -3, which translates to height of 36px and 24px respectively.

Please note that density only takes care of size and spacing of element, not the font-size, for font-size you will have use typography mixin.

Typography

This mixin includes styles related to the fonts used in your application, including the font family, size, weight, line-height, and letter-spacing. These style should be included at least once in your application.

Creating a size variant

Now assuming that you have already setup your project with Angular Material and keeping all things about density and typography in mind, lets create a smaller size variant for Angular Material button.

1. Create a file for size

Create a file src/styles/sizes/_index.scss with below content:

// src/styles/sizes/_index.scss
@use "@angular/material" as mat;
$regular-font-family: "'Inter', sans-serif";
$sm-typography: mat.define-typography-config(
  $font-family: $regular-font-family,
  $button:
    mat.define-typography-level(
      $font-size: 14px,
    ),
);
$sm-theme: mat.define-light-theme(
  (
    typography: $sm-typography,
    density: -2,
  )
);
.sm {
  @include mat.button-density($sm-theme);
  @include mat.button-typography($sm-theme);
  @include mat.progress-spinner-density($sm-theme);
  @include mat.progress-spinner-typography($sm-theme);
}

Few points to observe in above code:

We are creating a $sm-typography config, only with $button option. And we are giving 14px font-size to it. Note that we are also providing $font-family, if we do not provide, it will take default font-family, which is Roboto.
We are creating a $sm-theme with $sm-typography as typography config and -2 as density, which will give 28px base height to the button and it will also adjust the respective sizes
We are creating a .sm class and including mixins for density and typography for button and progress-spinner components

2. Import size file

The last step is to import size file in main styles file:

// src/styles.scss
@use "./styles/sizes";
// rest remains same

And then you simply wrap Angular Material buttons in sm class, you will see the small variants:

Conclusion

For more details, visit my course on angular-material.dev. Code is available on Github at Angular-Material-Dev/course-md-ng-my-app.

Course Announcement: A complete theming guide to Angular Material Components

Dharmen Shah — Tue, 21 Nov 2023 11:11:19 +0000

📢 It’s finally here!

🚀 A complete theming guide to Angular Material Components

✅ Typography, mixins, density, component’s themes, dark theme — covering everything

What’s included?

You will learn everything needed to incorporate and modify Angular Material Components theme, to be precise, below is what we will do:

Start with setting up the project
Create a custom theme
Modify typography
Create a dark theme
Use and modify components theme

You can view the course at:

https://angular-material.dev/courses/m2-ng-components

Toggle dark theme in Angular Material

Dharmen Shah — Sun, 24 Sep 2023 06:35:31 +0000

In one of our previous articles, we saw how to lazy load a dark theme. If you haven't already, please check it first:

Save some bytes when using multiple themes in angular material components

Dharmen Shah for Angular Material Dev ・ Sep 17

#angular #angularmaterial #angularcomponents #angularmaterialcomponents

Now, to load the "dark-theme.css" based on user's choice, we will create a simple service called "StyleManager":

// style-manager.service.ts

import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class StyleManager {
  isDark = false;

  toggleDarkTheme() {
    if (this.isDark) {
      this.removeStyle('dark-theme');
      document.body.classList.remove('dark-theme');
      this.isDark = false;
    } else {
      const href = 'dark-theme.css';
      getLinkElementForKey('dark-theme').setAttribute('href', href);
      document.body.classList.add('dark-theme');
      this.isDark = true;
    }
  }

  removeStyle(key: string) {
    const existingLinkElement = getExistingLinkElementByKey(key);
    if (existingLinkElement) {
      document.head.removeChild(existingLinkElement);
    }
  }
}

function getLinkElementForKey(key: string) {
  return getExistingLinkElementByKey(key) || createLinkElementWithKey(key);
}

function getExistingLinkElementByKey(key: string) {
  return document.head.querySelector(
    `link[rel="stylesheet"].${getClassNameForKey(key)}`
  );
}

function createLinkElementWithKey(key: string) {
  const linkEl = document.createElement('link');
  linkEl.setAttribute('rel', 'stylesheet');
  linkEl.classList.add(getClassNameForKey(key));
  document.head.appendChild(linkEl);
  return linkEl;
}

function getClassNameForKey(key: string) {
  return `style-manager-${key}`;
}

Then you can inject the "StyleManager" service, and call "toggleDarkTheme" whenever you want!

// src/app/app.component.ts

import { Component } from '@angular/core';
import { StyleManager } from './services/style-manager.service';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
  title = 'my-app';
  isDark = this.styleManager.isDark;

  private styleManager = inject(StyleManager);

  toggleDarkTheme() {
    this.styleManager.toggleDarkTheme();
    this.isDark = !this.isDark;
  }
}

That's it!!! For more information, read full article at:

angular-material.dev

Modify colors of Angular Material Button

Dharmen Shah — Mon, 18 Sep 2023 08:42:52 +0000

Struggling with changing colors of angular material buttons?

Not anymore! Read on...

Let’s assume that you have added Angular Material in your project and selected a pre-built theme to use.

We will create a custom-theme, which should get applied only when it’s inside .custom-theme class.

@use "@angular/material" as mat;

$custom-primary: mat.define-palette(mat.$pink-palette, 700, 500, 900);
$custom-accent: mat.define-palette(mat.$blue-grey-palette, A200, A100, A400);

$custom-theme: mat.define-dark-theme(
  (
    color: (
      primary: $custom-primary,
      accent: $custom-accent,
    ),
  )
);

.custom-theme {
  @include mat.button-theme($custom-theme);
}

Note that we have only included button-theme, because in our demo we only use that component. You can also use all-component-theme mixin to add all components’ themes, but it will increase the size of the final output style.

So, now with the above code, if in the HTML code, we simply wrap the buttons in custom-theme class, it will apply custom-theme to components inside it. Let’s look at the output:

That's a wrap!

For more details, read full article at:

angular-material.dev

Save some bytes when using multiple themes in angular material components

Dharmen Shah — Sun, 17 Sep 2023 09:18:55 +0000

Let's say you have a theme file called dark.scss like below.

// src/styles/themes/dark.scss

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

@use "../typography/config" as typography;
@use "../components";

$my-app-dark-primary: mat.define-palette(mat.$blue-grey-palette);
$my-app-dark-accent: mat.define-palette(mat.$amber-palette, A200, A100, A400);
$my-app-dark-warn: mat.define-palette(mat.$deep-orange-palette);
$my-app-dark-theme: mat.define-dark-theme(
  (
    color: (
      primary: $my-app-dark-primary,
      accent: $my-app-dark-accent,
      warn: $my-app-dark-warn,
    ),
  )
);

.dark-theme {
  @include mat.core-color($my-app-dark-theme);
  @include mat.button-color($my-app-dark-theme);
}

}
Now, in your assets array in angular.json, just exclude the dark theme file, see below code for example. With below code, dark theme file will be bundled as dark-theme.css in final output.

"styles": [
              "src/styles.scss",
              {
                "input": "src/styles/themes/dark.scss",
                "bundleName": "dark-theme",
                "inject": false
              }
            ],

Now, in your index.html, load dark-theme.css whenever required:

<link rel="stylesheet" href="dark-theme.css">

That's all! To know more, visit and read the full article now:
https://angular-material.dev/articles/angular-material-theming-system-complete-guide#create-a-dark-theme

Creating a custom form field control group using Angular Material

Dharmen Shah — Mon, 24 Jul 2023 15:13:14 +0000

Introduction

In one of my last tutorial, we learned how to create a completely reusable forms Angular.

In this guide we'll learn how to create a custom form for inputting address information and hook it up to work with <mat-form-field>.

How to build custom form group using Angular Material

Basic Address Form Component

In order to learn how to build custom form field controls, let's start with a simple form component that we want to work inside the form field. An address form that segments the parts of the address into their own form field inputs.

I created this form quickly using Angular Material schematic, simply run below command to create one:

ng generate @angular/material:address-form shared/address-form

It will generate template and class files like below:


<form [formGroup]="addressForm" novalidate (ngSubmit)="onSubmit()">
  <mat-card class="shipping-card">
    <mat-card-header>
      <mat-card-title>Shipping Information</mat-card-title>
    </mat-card-header>
    <mat-card-content>
      <div class="row">
        <div class="col">
          <mat-form-field>
            <input matInput placeholder="Company" formControlName="company">
          </mat-form-field>
        </div>
      </div>
      <div class="row">
        <div class="col">
          <mat-form-field>
            <input matInput placeholder="First name" formControlName="firstName">
            <mat-error *ngIf="addressForm.controls['firstName'].hasError('required')">
              First name is <strong>required</strong>
            </mat-error>
          </mat-form-field>
        </div>
        <div class="col">
          <mat-form-field>
            <input matInput placeholder="Last name" formControlName="lastName">
            <mat-error *ngIf="addressForm.controls['lastName'].hasError('required')">
              Last name is <strong>required</strong>
            </mat-error>
          </mat-form-field>
        </div>
      </div>
      <div class="row">
        <div class="col">
          <mat-form-field>
            <textarea matInput placeholder="Address" formControlName="address"></textarea>
            <mat-error *ngIf="addressForm.controls['address'].hasError('required')">
              Address is <strong>required</strong>
            </mat-error>
          </mat-form-field>
        </div>
      </div>
      <!-- Other form fields -->
    </mat-card-content>
    <mat-card-actions>
      <button mat-raised-button color="primary" type="submit">Submit</button>
    </mat-card-actions>
  </mat-card>
</form>


@Component({
  selector: 'app-address-form',
  templateUrl: './address-form.component.html',
  styleUrls: ['./address-form.component.css']
})
export class AddressFormComponent {
  private fb = inject(FormBuilder);
  addressForm = this.fb.group({
    company: null,
    firstName: [null, Validators.required],
    lastName: [null, Validators.required],
    address: [null, Validators.required],
    address2: null,
    city: [null, Validators.required],
    state: [null, Validators.required],
    postalCode: [null, Validators.compose([
      Validators.required, Validators.minLength(5), Validators.maxLength(5)])
    ],
    shipping: ['free', Validators.required]
  });

  hasUnitNumber = false;

  // rest of auto generated code
}

Now, in above code please make a few changes as listed below:

Remove usage of <mat-card> so that parent or consumer component has more control over UI.
Remove submit button, becuase this form is not going be used as a stand-alone form, rather this will be always used insider some other form.
Change all the fields' appearance to outline
Create a class called AddressForm and use it to create typed forms

So, now after the 1st, 2nd and 3rd change, the template will look like below:


<form
  novalidate
  [formGroup]="addressForm"
  class="address-form-container"
>
  <div class="row">
    <div class="col">
      <mat-form-field appearance="outline">
        <input
          matInput
          placeholder="Company"
          formControlName="company"
        />
      </mat-form-field>
    </div>
  </div>
  <div class="row">
    <div class="col">
      <mat-form-field appearance="outline">
        <input
          matInput
          placeholder="First name"
          formControlName="firstName"
        />
        <mat-error
          *ngIf="addressForm.controls['firstName'].hasError('required')"
        >
          First name is <strong>required</strong>
        </mat-error>
      </mat-form-field>
    </div>
    <div class="col">
      <mat-form-field appearance="outline">
        <input
          matInput
          placeholder="Last name"
          formControlName="lastName"
        />
        <mat-error
          *ngIf="addressForm.controls['lastName'].hasError('required')"
        >
          Last name is <strong>required</strong>
        </mat-error>
      </mat-form-field>
    </div>
  </div>
  <div class="row">
    <div class="col">
      <mat-form-field appearance="outline">
        <textarea
          matInput
          placeholder="Address"
          formControlName="address"
        ></textarea>
        <mat-error *ngIf="addressForm.controls['address'].hasError('required')">
          Address is <strong>required</strong>
        </mat-error>
      </mat-form-field>
    </div>
  </div>
  <!-- Other address fields will come here and submit button removed -->
</form>

And after 4th change, the will have a new file called address.ts:


import { FormControl } from '@angular/forms';

export class Address {
  constructor(
    public company: string | null = null,
    public firstName: string = '',
    public lastName: string = '',
    public address: string = '',
    public address2: string | null,
    public city: string = '',
    public state: string = '',
    public postalCode: number = 0,
    public shipping: AddressShipping = 'free'
  ) {}
}

export type AddressForm = {
  company: FormControl<string | null>;
  firstName: FormControl<string>;
  lastName: FormControl<string>;
  address: FormControl<string>;
  address2: FormControl<string | null>;
  city: FormControl<string>;
  state: FormControl<string>;
  postalCode: FormControl<number>;
  shipping: FormControl<AddressShipping>;
};

export type AddressShipping = 'free' | 'priority' | 'nextday';

and the component's class file will look like below:


@Component({
  selector: 'app-address-form',
  templateUrl: './address-form.component.html',
  styleUrls: ['./address-form.component.css']
})
export class AddressFormComponent {
  private fb = inject(FormBuilder);

  readonly freeShipping: AddressShipping = 'free';

  addressForm = this.fb.group<AddressForm>({
    company: this.fb.control(null),
    firstName: this.fb.control('', { nonNullable: true, validators: [Validators.required]}),
    lastName: this.fb.control('', { nonNullable: true, validators: [Validators.required]}),
    address: this.fb.control('', { nonNullable: true, validators: [Validators.required]}),
    address2: this.fb.control(null),
    city: this.fb.control('', { nonNullable: true, validators: [Validators.required]}),
    state: this.fb.control('', { nonNullable: true, validators: [Validators.required]}),
    postalCode: this.fb.control(0, { nonNullable: true, validators: Validators.compose([
      Validators.required, Validators.minLength(5), Validators.maxLength(5)]) }
    ),
    shipping: this.fb.control(this.freeShipping, { nonNullable: true, validators: Validators.required})
  });

  // rest of auto generated code
}

Providing our component as a `MatFormFieldControl`

The first step is to provide our new component as an implementation of the MatFormFieldControl interface that the <mat-form-field> knows how to work with. To do this, we will have our class implement MatFormFieldControl. Since this is a generic interface, we'll need to include a type parameter indicating the type of data our control will work with, in this case Address. We then add a provider to our component so that the form field will be able to inject it as a MatFormFieldControl.

@Component({
  ...
  providers: [
    { provide: MatFormFieldControl, useExisting: AddressFormComponent },
  ],
})
export class AddressFormComponent implements MatFormFieldControl<Address> {
  ...
}

This sets up our component, so it can work with <mat-form-field>, but now we need to implement the various methods and properties declared by the interface we just implemented. To learn more about the MatFormFieldControl interface, see the form field API documentation.

Implementing the methods and properties of `MatFormFieldControl`

`value`

This property allows someone to set or get the value of our control. Its type should be the same type we used for the type parameter when we implemented MatFormFieldControl. Since our component already has a value property, we don't need to do anything for this one.

`stateChanges`

Because the <mat-form-field> uses the OnPush change detection strategy, we need to let it know when something happens in the form field control that may require the form field to run change detection. We do this via the stateChanges property. So far the only thing the form field needs to know about is when the value changes. We'll need to emit on the stateChanges stream when that happens, and as we continue flushing out these properties we'll likely find more places we need to emit. We should also make sure to complete stateChanges when our component is destroyed.


stateChanges = new Subject<void>();

set value(address: Address | null) {
  address = address || new Address('', '', '', '', '', '', '', 0, this.freeShipping);
  this.addressForm.setValue(address);

  this.stateChanges.next();
}

ngOnDestroy() {
  this.stateChanges.complete();
}

`id`

This property should return the ID of an element in the component's template that we want the <mat-form-field> to associate all of its labels and hints with. In this case, we'll use the host element and just generate a unique ID for it.

static nextId = 0;

@HostBinding() id = `address-form-${AddressFormComponent.nextId++}`;

`placeholder`

This property allows us to tell the <mat-form-field> what to use as a placeholder. In this example, we'll do the same thing as matInput and <mat-select> and allow the user to specify it via an @Input(). Since the value of the placeholder may change over time, we need to make sure to trigger change detection in the parent form field by emitting on the stateChanges stream when the placeholder changes.

Note that as ours is a set of form-fields, and not individual form-field, we are not using placeholder anywhere in the template. But, I have given the code below in case you want to integrate it.

@Input()
get placeholder() {
  return this._placeholder;
}
set placeholder(plh) {
  this._placeholder = plh;
  this.stateChanges.next();
}
private _placeholder: string;

`ngControl` and `ControlValueAccessor`

This property allows the form field control to specify the @angular/forms control that is bound to this component.

Let's implement ControlValueAccessor so that our component can work with formControl and ngModel. As we are implementing ControlValueAccessor we will need to get a reference to the NgControl associated with our control and make it publicly available.

The easy way is to add it as a public property to your constructor and let dependency injection handle it:

constructor(
  ...,
  @Optional() @Self() public ngControl: NgControl,
  ...,
) { }

Now as our component implements ControlValueAccessor, to avoid cannot instantiate cyclic dependency error, instead of using the NG_VALUE_ACCESSOR provider, we will set the value accessor directly:

@Component({
  ...
})
export class AddressFormComponent implements MatFormFieldControl<Address>, ControlValueAccessor {
  constructor(
    ...,
    @Optional() @Self() public ngControl: NgControl,
    ...,
  ) {

    if (this.ngControl != null) {
      // Setting the value accessor directly (instead of using
      // the providers) to avoid running into a circular import.
      this.ngControl.valueAccessor = this;
    }
  }
}

For additional information about ControlValueAccessor see the API docs.

`focused`

This property indicates whether the form field control should be considered to be in a focused state. When it is in a focused state, the form field is displayed with a solid color underline. For the purposes of our component, we want to consider it focused if any of the part inputs are focused. We can use the focusin and focusout events to easily check this. We also need to remember to emit on the stateChanges when the focused stated changes stream so change detection can happen.

In addition to updating the focused state, we use the focusin and focusout methods to update the internal touched state of our component, which we'll use to determine the error state.

focused = false;

onFocusIn(event: FocusEvent) {
  if (!this.focused) {
    this.focused = true;
    this.stateChanges.next();
  }
}

onFocusOut(event: FocusEvent) {
  if (!this._elementRef.nativeElement.contains(event.relatedTarget as Element)) {
    this.touched = true;
    this.focused = false;
    this.onTouched();
    this.stateChanges.next();
  }
}

`empty`

This property indicates whether the form field control is empty. For our control, we'll consider it empty if all the fields are empty.

get empty() {
    const {
      value: {
        company,
        firstName,
        address2,
        address,
        city,
        lastName,
        postalCode,
        shipping,
        state,
      },
    } = this.addressForm;

    return (
      !company &&
      !firstName &&
      !address &&
      !address2 &&
      !city &&
      !lastName &&
      !postalCode &&
      !shipping &&
      !state
    );
  }

`shouldLabelFloat`

This property is used to indicate whether the label should be in the floating position. We'll use the same logic as matInput and float the placeholder when the input is focused or non-empty.

@HostBinding('class.floating')
get shouldLabelFloat() {
  return this.focused || !this.empty;
}

span {
  opacity: 0;
  transition: opacity 200ms;
}
:host.floating span {
  opacity: 1;
}

`required`

This property is used to indicate whether the input is required. <mat-form-field> uses this information to add a required indicator to the placeholder. Again, we'll want to make sure we run change detection if the required state changes.

@Input()
get required() {
  return this._required;
}
set required(req: BooleanInput) {
  this._required = coerceBooleanProperty(req);
  this.stateChanges.next();
}
private _required = false;

`disabled`

This property tells the form field when it should be in the disabled state. In addition to reporting the right state to the form field, we need to set the disabled state on the individual inputs that make up our component.

@Input()
  get disabled(): boolean {
    return this._disabled;
  }
  set disabled(value: BooleanInput) {
    this._disabled = coerceBooleanProperty(value);
    this._disabled ? this.addressForm.disable() : this.addressForm.enable();
    this.stateChanges.next();
  }
  private _disabled = false;

`errorState`

This property indicates whether the associated NgControl is in an error state. In this example, we show an error if the input is invalid and our component has been touched.

get errorState(): boolean {
    return this.addressForm.invalid && this.touched;
  }

`controlType`

This property allows us to specify a unique string for the type of control in form field. The <mat-form-field> will add a class based on this type that can be used to easily apply special styles to a <mat-form-field> that contains a specific type of control. In this example we'll use address-form as our control type which will result in the form field adding the class mat-form-field-type-address-form.

controlType = 'address-form';

`setDescribedByIds(ids: string[])`

This method is used by the <mat-form-field> to set element ids that should be used for thearia-describedby attribute of your control. The ids are controlled through the form field as hints or errors are conditionally displayed and should be reflected in the control's aria-describedby attribute for an improved accessibility experience.

The setDescribedByIds method is invoked whenever the control's state changes. Custom controls need to implement this method and update the aria-describedby attribute based on the specified element ids. Below is an example that shows how this can be achieved.

Note that the method by default will not respect element ids that have been set manually on the control element through the aria-describedby attribute. To ensure that your control does not accidentally override existing element ids specified by consumers of your control, create an input called userAriaDescribedby like followed:

@Input('aria-describedby') userAriaDescribedBy: string;

The form field will then pick up the user specified aria-describedby ids and merge them with ids for hints or errors whenever setDescribedByIds is invoked.

setDescribedByIds(ids: string[]) {
    const controlElement = this._elementRef.nativeElement.querySelector(
      '.address-form-container'
    )!;
    controlElement.setAttribute('aria-describedby', ids.join(' '));
  }

`onContainerClick(event: MouseEvent)`

This method will be called when the form field is clicked on. It allows your component to hook in and handle that click however it wants. The method has one parameter, the MouseEvent for the click. In our case we'll just focus the first <input> if the user isn't about to click an <input> anyways.

@ViewChild('company')
  companyInput!: HTMLInputElement;
  @ViewChild('firstName')
  firstNameInput!: HTMLInputElement;
  @ViewChild('lastName')
  lastNameInput!: HTMLInputElement;
  @ViewChild('address')
  addressInput!: HTMLTextAreaElement;
  @ViewChild('address2')
  address2Input!: HTMLTextAreaElement;
  @ViewChild('city')
  cityInput!: HTMLInputElement;
  @ViewChild('state')
  stateInput!: MatSelect;
  @ViewChild('postalCode')
  postalCodeInput!: HTMLInputElement;
  @ViewChild('shipping')
  shippingInput!: MatRadioGroup;

onContainerClick() {
    if (this.addressForm.controls.company.valid) {
      this._focusMonitor.focusVia(this.companyInput, 'program');
    } else if (this.addressForm.controls.firstName.valid) {
      this._focusMonitor.focusVia(this.firstNameInput, 'program');
    } else if (this.addressForm.controls.lastName.valid) {
      this._focusMonitor.focusVia(this.lastNameInput, 'program');
    } else if (this.addressForm.controls.address.valid) {
      this._focusMonitor.focusVia(this.addressInput, 'program');
    } else if (this.addressForm.controls.address2.valid) {
      this._focusMonitor.focusVia(this.address2Input, 'program');
    } else if (this.addressForm.controls.city.valid) {
      this._focusMonitor.focusVia(this.cityInput, 'program');
    } else if (this.addressForm.controls.state.valid) {
      this._focusMonitor.focusVia(
        this.stateInput._elementRef.nativeElement,
        'program'
      );
    } else if (this.addressForm.controls.postalCode.valid) {
      this._focusMonitor.focusVia(this.postalCodeInput, 'program');
    } else {
      this.shippingInput._radios.first.focus(undefined, 'program');
    }
  }

Improving accessibility

One significant piece of information is missing for screen reader users. They won't be able to tell what this input group represents. To improve this, we should add a label for the group element using either aria-label or aria-labelledby.

It's recommended to link the group to the label that is displayed as part of the parent <mat-form-field>. This ensures that explicitly specified labels (using <mat-label>) are actually used for labelling the control.

In our concrete example, we add an attribute binding for aria-labelledby and bind it to the label element id provided by the parent <mat-form-field>.

export class AddressFormComponent implements ... {
  ...

  constructor(...
              @Optional() public parentFormField: MatFormField,) {

@Component({
  selector: 'app-address-form',
  template: `
    <form [formGroup]="addressForm"
         [attr.aria-labelledby]="parentFormField?.getLabelId()">

Trying it out

Now that we've fully implemented the interface, we're ready to try our component out! All we need to do is place it inside a <mat-form-field>, which is inside another form:

<div [formGroup]="form">
  <mat-card class="shipping-card">
    <mat-card-header>
      <mat-card-title>Shipping Information</mat-card-title>
    </mat-card-header>
    <mat-card-content>
      <mat-form-field  appearance="outline">
        <app-address-form formControlName="address" required></app-address-form>
      </mat-form-field>
    </mat-card-content>
  </mat-card>
</div>

Full code is available on github/reusable-material-form.

InDepth Guide for Creating Nested and Reusable Forms

Dharmen Shah — Tue, 30 Aug 2022 05:42:12 +0000

In this tutorial you will learn how to create and use form-groups. And we will also learn how to achieve complete reusability.

Introduction

In web applications, we can have large forms, like account registration form, profile creation form, credit card form, address form, etc. These large forms generally have a set of fields which are repeated in them.

For example, address fields are generally available in all the registration forms. In this tutorial, we will learn how to wrap such fields in a reusable form, so that it can be used as nested form any other form.

In this tutorial, we will discuss 4 approaches to create a form and we will also look at pros and cons for each:

How to create and use form-group
How to create nested form-groups
How to use child component with nested form-group
How to create reusable form with Composite ControlValueAccessor

How to create and use FormGroup

Forms typically contain several related controls. Reactive forms provide two ways of grouping multiple related controls into a single input form: FormGroup and FormArray. For this tutorial, we will focus on FormGroup.

Just as a form control instance gives you control over a single input field, a form group instance tracks the form state of a group of form control instances (for example, a form). Each control in a form group instance is tracked by name when creating the form group.

We will take an example of Profile form, which will have input fields for name, email, address lines, city, state, zip-code and country.

The form-group for the same looks like below:

// src/app/simple-form-group/simple-form-group.component.ts

@Component({
  selector: "app-simple-form-group",
  templateUrl: "simple-form-group.component.html",
})
export class SimpleFormGroupComponent {
  profileFormGroup = new FormGroup<SimpleProfileForm>({
    name: new FormControl("", {
      validators: [Validators.required],
      nonNullable: true,
    }),
    email: new FormControl("", {
      validators: [Validators.email, Validators.required],
      nonNullable: true,
    }),
    line1: new FormControl("", {
      validators: [Validators.required],
      nonNullable: true,
    }),
    // other address form controls
  });

  readonly COUNTRIES = COUNTRIES;
  constructor() {}

  get nameFC() {
    return this.profileFormGroup.get("name");
  }
  get emailFC() {
    return this.profileFormGroup.get("email");
  }
  get line1FC() {
    return this.profileFormGroup.get("line1");
  }
  // other form-control getters
}

export type SimpleProfileForm = {
  name: FormControl<string>;
  email: FormControl<string>;
  line1: FormControl<string>;
  line2?: FormControl<string | null>;
  zipCode: FormControl<string>;
  city: FormControl<string>;
  state: FormControl<string>;
  country: FormControl<string>;
};

Notice that we are also taking advantage of the strictly typed forms feature, which is introduced in Angular 14.

In the above code, we are simply creating a FormGroup with all the fields as FormControl. The HTML template code can look like below:

<!-- src/app/simple-form-group/simple-form-group.component.html -->

<form [formGroup]="profileFormGroup">
  <h2>Basic Information</h2>
  <div>
    <label for="name">Name*</label>
    <input
      type="name"
      formControlName="name"
      id="name"
      required
      [ngClass]="{
        'is-invalid': nameFC?.invalid && (nameFC?.touched || nameFC?.dirty)
      }"
    />
    <div class="invalid-feedback">Name is required</div>
  </div>
  <!-- other basic information fields -->
  <div>
    <h2>Address</h2>
    <div>
      <label for="line1">Line 1*</label>
      <input
        [id]="'line1'"
        [name]="'line1'"
        autocomplete="address-line1"
        formControlName="line1"
        required
        type="text"
        [ngClass]="{
          'is-invalid': line1FC?.invalid && (line1FC?.touched || line1FC?.dirty)
        }"
      />
      <div class="invalid-feedback">Address line 1 is required</div>
    </div>
    <!-- other address fields -->
  </div>
  <button type="submit" [disabled]="profileFormGroup.invalid">
    Submit form
  </button>
</form>

The formControlName input provided by the FormControlName directive binds each individual input to the form control defined in FormGroup. The form controls communicate with their respective elements. They also communicate changes to the form group instance, which provides the source of truth for the model value.

Pros

Simple and straight-forward template and form-group

Cons

Difficult to create and maintain complex form models
Logical segregation is missing between set of fields

How to create nested form-groups

When building complex forms, managing the different areas of information is easier in smaller sections. Using a nested form group instance lets you break large form groups into smaller, more manageable ones.

Let’s group address related fields in a nested group:

// src/app/nested-from-group/nested-from-group.component.ts

@Component({
  selector: "app-nested-form-group",
  templateUrl: "nested-form-group.component.html",
})
export class NestedFormGroupComponent {
  profileFormGroup = new FormGroup<ProfileForm>({
    name: new FormControl("", {
      validators: [Validators.required],
      nonNullable: true,
    }),
    email: new FormControl("", {
      validators: [Validators.email, Validators.required],
      nonNullable: true,
    }),
    address: new FormGroup<AddressForm>({
      line1: new FormControl("", {
        validators: [Validators.required],
        nonNullable: true,
      }),
      // other address fields...
    }),
  });
}

type ProfileForm = {
  name: FormControl<string>;
  email: FormControl<string>;
  address: FormGroup<AddressForm>;
};

type AddressForm = {
  line1: FormControl<string>;
  line2?: FormControl<string | null>;
  zipCode: FormControl<string>;
  city: FormControl<string>;
  state: FormControl<string>;
  country: FormControl<string>;
};

Notice that now in profileForm address related fields are grouped in address element. We also created a AddressForm type to get better type safety, and better autocomplete in IDEs. Let’s group group nested form in the template:

<!-- src/app/nested-from-group/nested-form-group.component.html -->

<form [formGroup]="profileFormGroup">
  <h2>Basic Information</h2>
  <!-- basic information fields -->
  <!-- notice the usage of formGroupName below -->
  <div formGroupName="address">
    <h2>Address</h2>
    <div>
      <label for="line1">Line 1*</label>
      <input
        [id]="'line1'"
        [name]="'line1'"
        autocomplete="address-line1"
        formControlName="line1"
        required
        type="text"
        [ngClass]="{
          'is-invalid': line1FC?.invalid && (line1FC?.touched || line1FC?.dirty)
        }"
      />
      <div class="invalid-feedback">Address line 1 is required</div>
    </div>
    <!-- other address related fields -->
  </div>
  <button type="submit" [disabled]="profileFormGroup.invalid">
    Submit form
  </button>
</form>

We added the formGroupName directive to indicate that children form controls are part of address form-group.

Pros

Easy to create and maintain complex form models
Logical segregation is present between set of fields

Cons

Larger template due to more fields and complex form

How to use child component with nested form-group

In the previous section, we achieved logical separation in class, but our template is still complex. We will create another component to handle template complexity.

// src/app/nested-form-group-child/address-form/address-form.component.ts

@Component({
  selector: "app-address-form",
  templateUrl: "address-form.component.html",
})
export class AddressFormComponent {
  @Input("formGroup") addressFormGroup!: FormGroup;

  get line1FC() {
    return this.addressFormGroup.get("line1");
  }
  // other form-control getters...
}

We created AddressFormComponent. It has an input property called formGroup, through which parent components can pass the form-group. Let’s take a look at template:

<!-- src/app/nested-form-group-child/address-form/address-form.component.html -->

<div [formGroup]="addressFormGroup">
  <h2>Address</h2>
  <div>
    <label for="line1">Line 1*</label>
    <input
      [id]="'line1'"
      [name]="'line1'"
      autocomplete="address-line1"
      formControlName="line1"
      required
      type="text"
      [ngClass]="{
        'is-invalid': line1FC?.invalid && (line1FC?.touched || line1FC?.dirty)
      }"
    />
    <div class="invalid-feedback">Address line 1 is required</div>
  </div>
  <!-- other address fields -->
</div>

The template is pretty simple, it just has the address related fields. And below is how we would use it in parent component:

<!-- src/app/nested-form-group-child/nested-form-group-child.component.html -->

<form [formGroup]="profileFormGroup">
  <!-- basic fields →

  <!-- notice the usage of child component -->
  <app-address-form [formGroup]="addressFormGroup"></app-address-form>

  <button type="submit" [disabled]="profileFormGroup.invalid">
    Submit form
  </button>
</form>

And in the class, we would get the address form-group like below:

// src/app/nested-from-group/nested-from-group.component.ts

@Component({
  // ...
})
export class NestedFormGroupChildComponent {
  profileFormGroup = new FormGroup<ProfileForm>({ /*...*/ });

  get addressFormGroup() {
    return this.profileFormGroup.get("address") as FormGroup;
  }
}

Pros

Simpler templates a. With this approach now we can handle everything related to address in AddressFormComponent so that our main component is much simpler to handle.

Cons

Not completely re-usable a. If you want to use this component as a stand-alone form component, it’s not possible for now

How to create reusable form with Composite `ControlValueAccessor`

In the previous section, we created a component and moved the address form’s template into it. But, it’s still not completely re-suable. By completely re-usable what I mean is:

The logic, error handling and address form creation should be part of address-component and not the parent component
The component should be usable inside any form
The component should be usable with both, template driven and reactive forms
The component should support native form-control features, so that the parent or consumer component can take advantage of that, for example showing errors if overall address-form is invalid

In this section we will learn how to create a completely reusable form, that can be used as both, inside other forms and as a stand-alone form. And the technique which we are going to use is called “Composite ControlValueAccessor”, referred from Kara Erickson in AngularConnect 2017.

Our goal is to use the address form something like below:

<!-- src/app/reusable-form/reusable-form-wrapper/reusable-form-wrapper.component.html -->

<form [formGroup]="profileFormGroup">
  <!-- other basic information fields -->
  <app-reusable-form formControlName="address"></app-reusable-form>
</form>

ControlValueAccessor

A ControlValueAccessor acts as a bridge between the Angular forms API and a native element in the DOM. Any component or directive can be turned into form-control by implementing the ControlValueAccessor interface and registering itself as an NG_VALUE_ACCESSOR provider.

Among others the interface defines two important methods — writeValue and registerOnChange.

The writeValue method is used by formControl to set the value to the native form control. The registerOnChange method is used by formControl to register a callback that is expected to be triggered every time the native form control is updated. It is your responsibility to pass the updated value to this callback so that the value of respective Angular form control is updated. The registerOnTouched method is used to indicate that a user interacted with a control.

Here is the diagram that demonstrates an interaction:

From Never again be confused when implementing ControlValueAccessor in Angular forms - Angular inDepth

To learn more about ControlValueAccessor, you can read this indepth guide. If you are looking for a practical example, you can refer to my earlier article about date input and tutorial about managing object in form-control.

Composite ControlValueAccessors

In earlier articles and tutorials, we saw usage of ControlValueAccessor with one <input>. But, the advantage of using ControlValueAccessor is you can have more inputs with it if you want.

We just need to handle all 4 required methods of that interface and it will just work, no matter how we handle it internally.

Reusable Form

One thing from previous section is clear, we want to use the same template and internally, we will manage the fields’ states with a form-group, so our template will look like below:

<!-- src/app/reusable-form/reusable-form.component.html -->

<div role="group" [formGroup]="form">
  <div>
    <label for="line1">Line 1*</label>
    <input
      id="line1"
      name="line1"
      autocomplete="address-line1"
      formControlName="line1"
      required
      type="text"
      [ngClass]="{
        'is-invalid': line1FC?.invalid && (line1FC?.touched || line1FC?.dirty)
      }"
    />
    <div class="invalid-feedback">Address line 1 is required</div>
  </div>
  <!-- other address fields -->
</div>

To manage the address object, we will create a class. This will be used in later stage in class of above template:

// src/app/reusable-form/address.ts

export class Address {
  constructor(
    public line1: string = "",
    public zipCode: string = "",
    public city: string = "",
    public state: string = "",
    public country: string = "",
    public line2?: string | null
  ) {}

  isValid() {
    return (
      this.line1 && this.city && this.country && this.state && this.zipCode
    );
  }
}

We will have the above Address class as value for the form. Just like string, number and boolean, we can also have object stored in form-control. You can read more about it at the tutorial about managing object in form-control.

And for validation, you can have your own logic to validate the address, but for now we will keep it simple. We will use this when we implement validation.

Next, based on previous articles about ControlValueAccessor, we will start with implementing ControlValueAccessor interface and the NG_VALUE_ACCESSOR as provider:

// src/app/reusable-form/reusable-form.component.ts

@Component({
  selector: "app-reusable-form",
  templateUrl: "reusable-form.component.html",
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: ReusableFormComponent,
      multi: true,
    },
  ],
})
export class ReusableFormComponent implements ControlValueAccessor {
  form = new FormGroup<AddressForm>({
    line1: new FormControl("", {
      validators: Validators.required,
      nonNullable: true,
    }),
    // other address fields' form-controls
  });

  writeValue(value: Address | null): void {}

  registerOnChange(fn: (val: Partial<Address> | null) => void): void {}

  registerOnTouched(fn: () => void): void {}

  setDisabledState(disabled: boolean) {}
}

writeValue

// src/app/reusable-form/reusable-form.component.ts

  writeValue(value: Address | null): void {
    const address = this.createAddress(value);
    this.form.patchValue(address);
  }

  private createAddress(value: Partial<Address> | null) {
    return new Address(
      value?.line1 || "",
      value?.zipCode || "",
      value?.city || "",
      value?.state || "",
      value?.country || "",
      value?.line2
    );
  }

In this, we will first convert the value coming in to the instance of Address and then, will call form.patchValue and it will update all the fields, of which values are updated.

registerOnChange

// src/app/reusable-form/reusable-form.component.ts

registerOnChange(fn: (val: Partial<Address> | null) => void): void {
    this.form.valueChanges.subscribe((value) => {
      const address = this.createAddress(value);
      fn(address);
    });
  }

We are using valueChanges observable to handle registerOnChange. valueChanges observable emits for all the child form-fields, so it is a perfect fit for registerOnChange.

Now, as we are listening for valueChanges, we will have to revisit and fix writeValue’s patchValue, because everytime patchValue is called, valueChanges will trigger, we don’t want that.

// src/app/reusable-form/reusable-form.component.ts

  writeValue(value: Address | null): void {
    const address = this.createAddress(value);
    this.form.patchValue(address, { emitEvent: false });
  }

As you notice above, we are setting emitEvent to false, so that it doesn’t trigger valueChanges.

registerOnTouched

// src/app/reusable-form/reusable-form.component.ts

onTouched: any;

registerOnTouched(fn: () => void): void {
    this.onTouched = fn;
  }

We want the form to be touched, anytime any child form-control is touched. So, we will call onTouched in the template as well, with all child form-controls:

<!-- src/app/reusable-form/reusable-form.component.html -->

<div role="group" [formGroup]="form">
  <div>
    <label for="line1">Line 1*</label>
    <!-- removed other attributes/properties for brevity -->
    <input
      (blur)="onTouched()"
    />
  </div>
  <!-- other address fields -->
</div>

setDisabledState

// src/app/reusable-form/reusable-form.component.ts

setDisabledState(disabled: boolean) {
    disabled ? this.form.disable() : this.form.enable();
  }

Validation

To handle validation, we will first add provider, and implement the Validator interface:

// src/app/reusable-form/reusable-form.component.ts

@Component({
  // ...
  providers: [
    // ...
    {
      provide: NG_VALIDATORS,
      useExisting: ReusableFormComponent,
      multi: true,
    },
  ],
})
export class ReusableFormComponent implements ControlValueAccessor, Validator {

  // ...
  validate(control: AbstractControl<Address>): ValidationErrors | null {}
}

validate

// src/app/reusable-form/reusable-form.component.ts

validate(control: AbstractControl<Address>): ValidationErrors | null {
    const value = control.value;
    return value && value.isValid() ? null : { address: true };
  }

Here we are going to use the Address class’s isValid method and based on that we will return the error.

Multiple instances

Although our form is ready now to be used, there is still one issue with it. If this component is being used within the same UI, then the form controls may not work properly, because they all will have have same name and id attributes. And, this component itself doesn’t have id, which can be helpful for testing.

To fix this, first let’s introduce an host property called id:

// src/app/reusable-form/reusable-form.component.ts

@Component({
  // ...
  host: {
    "[id]": "id",
  },
})
export class ReusableFormComponent {
  id = `address-input`;
}

Next, we will add a static counter, which we will increment with each instance of this component:

// src/app/reusable-form/reusable-form.component.ts

@Component({
  // ...
})
export class ReusableFormComponent {

  static nextId = 0;
  id = `address-input-${ReusableFormComponent.nextId++}`;

}

And lastly, we will use this id with all inputs’ id and name attributes. And also in their <label>s’ for attribute:

<!-- src/app/reusable-form/reusable-form.component.html -->

<div role="group" [formGroup]="form">
  <div>
    <label [htmlFor]="id + '-line1'">Line 1*</label>
    <!-- other attributes removed for brevity -->
    <input
      [id]="id + '-line1'"
      [name]="id + '-line1'"
    />
  </div>
  <!-- other address fields -->
</div>

With this, our completely reusable address form is ready.

Conclusion

In this tutorial we learned about how to create and use form-groups. Then we learned about how to create nested form-groups and how to use it with child components. And with each of those approaches, we also learned their pros and cons.

In the last, but very important section, we learned about how to create a completely reusable form component with composite ControlValueAccessor.

I have uploaded the code at GitHub, you can also take a look at it on stackblitz.

InDepth Guide for Customizing Angular Material Button

Dharmen Shah — Sat, 11 Jun 2022 10:31:37 +0000

Introduction

It is a very common need in almost all applications to modify the components provided by 3rd party libraries. Those modifications are generally done for:

Changing the styles
Adding a missing feature

And it is very crucial for such libraries to provide ways to achieve those modifications easily.

In the first part of this tutorial we will learn how to modify styles so that our changes do not conflict with future updates of Angular Material library. As a bonus, I will provide a list of thumb rules which you should follow while making any style changes.

In the second part of this tutorial, we will learn all the ways to customize angular material buttons and decide which is better.

By end of this article, you will have idea about below topics:

How to create attribute directive
How to create dynamic component
When to create component and when to create directive
How to effectively modify any 3rd party library’s components, for both, to add a feature and to change the styles

Angular Material Button

Angular Material’s buttons are already enhanced with Material design and ink ripples, and they also have a range of presentation options.

You can change the look and feel of buttons by using different attribute directives for different situations and needs. For instance mat-button is a rectangular button with text content, mat-raised-button is the same as mat-button, but with elevation and mat-icon-button is circular and it’s meant to contain an icon. You can check all variants on the official site.

And there are 3 theme colors provided with all variants: primary, accent and warn.

Now, even with these many variants and options, we may need to modify the default Angular Material button to achieve a feature or change of style. Let’s look and learn how to make both the changes effectively.

How to change styles

Before moving into how to change styles, let’s first understand some rules to avoid any conflicting changes. These rules are consolidated from customizing component styles guidelines.

Thumb rules

Keep below rules in mind whenever you want to change styles of any Angular Material component.

Define custom styles for a component’s host element
Change styles which affect either position or layout of that component
1. margin, position, top, left, transform, z-index, etc.
Apply above styles modifications by defining a custom CSS class and applying it to component’s host element
Do not change the styles which affect size or internal layout of the component
1. padding, height, width, or overflow
Do not change or override the styles of internal elements of Angular Material components, like in Angular Material button, there are some internal components which produce ripple effect, we should avoid modifying styles of such components
Provide custom styles to overlay components, like MatDialog, MatMenu, etc. through panelClass property. Add that class to your global stylesheet after including theme mixins.

By following above rules, not just for Angular Material components but any component library, we can safely achieve needed modifications and avoid causing breaking styles.

Now, keeping the above rules in mind, we will try to change styles of Angular Material buttons. For this tutorial, we will focus on below 2 styles changes:

Color
Shape

And at the end of the section we will also have a brief look for size and typography.

Color

The very basic change we may need to font-color and background-color of buttons. And that, too with different states, like :hover, :focus and :active.

Some time back I wrote an article about “Angular Material Theming System: Complete Guide” and in that I wrote a section titled “Customizing Angular Material Component Styles”. In that section, I have explained how to modify the Angular Material button’s colors.

But, that approach was complex, difficult to read, hard to debug and not future safe. The reason behind that was I re-created many SASS functions and mixins, which are supposed to be used by only internal elements of buttons and used them to achieve desired changes. Now, if the Angular Material team plans to change any internal styles, those modifications will break.

So, let’s look at a more easy and recommended way to achieve color modifications.

Let’s assume that you have added Angular Material in your project and selected a pre-built theme to use.

At this time, your style.scss looks like below:

// styles.scss
html,
body {
  height: 100%;
}
body {
  margin: 0;
  font-family: Roboto, "Helvetica Neue", sans-serif;
}

We will create a custom-theme, which should get applied only when it’s inside .custom-theme class.

@use "@angular/material" as mat;

$custom-primary: mat.define-palette(mat.$pink-palette, 700, 500, 900);
$custom-accent: mat.define-palette(mat.$blue-grey-palette, A200, A100, A400);

$custom-theme: mat.define-dark-theme(
  (
    color: (
      primary: $custom-primary,
      accent: $custom-accent,
    ),
  )
);

.custom-theme {
  @include mat.button-theme($custom-theme);
  @include mat.progress-spinner-theme($custom-theme);
}

Note that we have only included button-theme and progress-spinner-theme, because in our demo we only use those 2 components. You can also use all-component-theme mixin to add all components’ themes, but it will increase the size of the final output style. For a more detailed understanding, please refer to the article “Angular Material Theming System: Complete Guide”.

So, now with the above code, if in the HTML code, we simply wrap the main container with custom-theme class, it will apply custom-theme to components inside it. Let’s look at the output:

Shape

Next, let’s change the shape. We want to add a shape variant such that buttons have a rounded borders.

Now, according to thumb-rules discussed earlier, we can change the styles of host-element which affect the layout of the component itself. So, to achieve the shape change, we can simply add a class with needed changes and apply it safely to Angular Material buttons:

.button-rounded {
  border-radius: 25% / 50%;
}

Now, if you apply the class button-rounded, you won’t see the change. The reason behind that is all variants of Angular Material buttons have their own border-radius already applied like below:

.mat-raised-button {
    // rest
    border-radius: 4px;
}

So, considering selector specificity, we will have to modify our code like below:

.button-rounded {
  &.mat-button,
  &.mat-raised-button,
  &.mat-flat-button {
    border-radius: 25% / 50%;
  }
}

Now, it will look perfect in the output:

Other styles changes

Apart from color and size, there can be more changes needed. Let’s briefly look at some and how to modify them.

Size

Modifications of size are not recommended, because it violates our thumb rules. Size customizations can lead to breaking changes with future updates.

And the Angular Material team has already followed material guidelines for the size, which we should not change.

Typography

This can be easily changed by using standard Angular Material theme mixins.

$custom-theme: mat.define-light-theme((
   color: (
     primary: $custom-primary,
     accent: $custom-accent,
   ),
   typography: $custom-typography,
  ));

For more details, see "Modify typography".

Next, we will look into how to add a spinner in the button.

How to add `MatProgressSpinner`

As mentioned in the heading, we will show a MatProgressSpinner when loading is set with Angular Material’s button.

Now, there are 3 ways to achieve that. Let’s look at them below and what are the pros and cons of each.

Template Interpolation
Wrapper Component
Directive

Template Interpolation

For template interpolation, your code may look like this:

<button mat-button [disabled]="isLoading">
    <mat-spinner *ngIf="isLoading"></mat-spinner>
    Action
</button>

Pros

The main advantage of above code is quick, readable and easy to customize as and when needed.

Cons

Repetition: Above code is fine, but you will have to repeat the same lines and conditions at all places wherever you want to show MatProgressSpinner in buttons.
Changes at all places: If you want to change something, for example size of MatProgressSpinner, you will have to find out all such instances and do the change.

Wrapper Component

Another approach and to overcome challenges faced with template interpolation, we can think of proceeding with creating a wrapper component with needed inputs, like below:

@Component({
    selector: 'app-button',
    template: `
        <button mat-button>
            <mat-spinner *ngIf="loading"></mat-spinner>
            <ng-content></ng-content>
        </button>
    `
})
export class AppButtonComponent {
    @Input() loading: boolean;
}

Pros

Changes at all places: With the above, now you can use app-button everywhere to get the same button with mat-spinner.
Reusability: And if you want to change anything, you just need to change in this component and it will reflect at all places.
Customizations: As we are using component, we can make template customizations easily

Cons

Native component properties: Let’s assume that at different places, we want to use different variants of the Angular Material button. Now for color, you can simply add one more input and get all the variants of color. But if you want to use different presentations, like mat-flat-button or mat-icon-button, things will start becoming more complex.
Events: Apart from variants, you will also have to handle events, like (click). You will have to propagate the click event using @Output() up to its parent component.
Other directives' support: Angular Material button supports it’s own MatTooltip and MatBadge directives out of the box. To achieve support of all of the above in a wrapper component is not only difficult but complex and hard to maintain.

Directive

With directive, we will first start with an input of loading state, which will show/hide MatProgressSpinner and also disable/enable the MatButton. Let’s start with basic code:

@Directive({
  selector: `button`,
})
export class ButtonDirective implements OnChanges {
  @Input() loading = false;

  constructor() {}

  ngOnChanges(changes: SimpleChanges): void {
    if (!changes['loading']) {
      return;
    }

    // Create/destroy spinner
  }

  private createSpinner(): void {}

  private destroySpinner(): void {}
}

In the above code, we are creating a directive with tag selector, so that it works with all <button>s. We have added an @Input() called loading, which will show/hide the spinner inside button.

Now, to show the spinner, we are going to create the MatProgressSpinnercomponent dynamically and will place it inside thebuttonwhenloading` is set to true.

typescript @Directive({ selector:button`,
})
export class ButtonDirective implements OnChanges {

private spinner!: ComponentRef | null;

ngOnChanges(changes: SimpleChanges): void {
if (!changes['loading']) {
return;
}

if (changes['loading'].currentValue) {
    // disable the `MatButton`
    this.createSpinner();
  } else if (!changes['loading'].firstChange) {
    // enable the `MatButton`
    this.destroySpinner();
  }

}
}
`

Above code is simple, we are creating and destroying spinner based on loading’s current value.

typescript @Directive({ selector:button`,
})
export class ButtonDirective implements OnChanges {

@Input() color: ThemePalette;

constructor(
private matButton: MatButton,
private viewContainerRef: ViewContainerRef,
private renderer: Renderer2
) {}

private createSpinner(): void {
if (!this.spinner) {
this.spinner = this.viewContainerRef.createComponent(MatProgressSpinner);
this.spinner.instance.color = this.color;
this.spinner.instance.diameter = 20;
this.spinner.instance.mode = 'indeterminate';
this.renderer.appendChild(
this.matButton._elementRef.nativeElement,
this.spinner.instance._elementRef.nativeElement
);
}
}

private destroySpinner(): void {
if (this.spinner) {
this.spinner.destroy();
this.spinner = null;
}
}
}
`

In the above code, first we added an @Input() to read the current color. We will use this property to set the color of the spinner.

Then, we provided MatButton, ViewContainerRef and Renderer2 classes in the constructor.

In the createSpinner method, we are simply creating the MatProgressSpinner dynamically and storing its reference in spinner, so that we can destroy it later on. Notice how we created it dynamically:

typescript this.spinner = this.viewContainerRef.createComponent(MatProgressSpinner);

And after creating, we are appending it to the HTML element of MatButton, with help of Renderer2:

typescript this.renderer.appendChild( this.matButton._elementRef.nativeElement, this.spinner.instance._elementRef.nativeElement );

And at last, in the destroySpinner method, we are destroying the spinner component and cleaning it up by assigning null value.

typescript @Directive({ selector:button`,
})
export class ButtonDirective implements OnChanges {

@Input() disabled = false;

ngOnChanges(changes: SimpleChanges): void {

// ...

if (changes['loading'].currentValue) {
this.matButton._elementRef.nativeElement.classList.add('button-loading');
this.matButton.disabled = true;
this.createSpinner();
} else if (!changes['loading'].firstChange) {
this.matButton._elementRef.nativeElement.classList.remove(
'button-loading'
);
this.matButton.disabled = this.disabled;
this.destroySpinner();
}
}
}
`

The last part is to make the MatButtton disabled when loading is true. Apart from disabling, we are also toggling a class button-loading with it to achieve the desired styles.

Below is the styles code for button-loading class:

`scss
.button-loading {
.mat-button-wrapper {
visibility: hidden;
}

.mat-progress-spinner {
position: absolute;
top: calc(50% - 10px);
left: calc(50% - 10px);
}
}
`

And the final code for directive looks like below:

typescript @Directive({ selector:button`,
})
export class ButtonDirective implements OnChanges {
private spinner!: ComponentRef | null;

@Input() loading = false;
@Input() disabled = false;
@Input() color: ThemePalette;

constructor(
private matButton: MatButton,
private viewContainerRef: ViewContainerRef,
private renderer: Renderer2
) {}

ngOnChanges(changes: SimpleChanges): void {
if (!changes['loading']) {
return;
}

if (changes['loading'].currentValue) {
  this.matButton._elementRef.nativeElement.classList.add('button-loading');
  this.matButton.disabled = true;
  this.createSpinner();
} else if (!changes['loading'].firstChange) {
  this.matButton._elementRef.nativeElement.classList.remove(
    'button-loading'
  );
  this.matButton.disabled = this.disabled;
  this.destroySpinner();
}

}

private destroySpinner(): void {
if (this.spinner) {
this.spinner.destroy();
this.spinner = null;
}
}
}
`

Above code is referenced from: Button | Angular Material Extensions (ng-matero.github.io)

Now, with Angular Material buttons, you just need to set loading to show a spinner inside of it. Let’s take a look at output:

Let’s look at the above approach’s pros and cons.

Pros

Native component properties: As you can see in the output, the directive works with all variants of MatButton
Events: Also, there is no need to write extra code handle event
Other directives' support: As we used directive, other library directives’ support, like MatBadge, MatTooltip still exists

Cons

No template control: We do not have template control with this approach compared to wrapper component and inline template interpolation
More DOM manipulation: As we do not have template control, we have to do every template change through DOM manipulation

So, compared with template interpolation and wrapper components, the reusability without losing default features is the main and biggest advantage of this approach. And that’s why, one should try to achieve such customizations with usage of directive.

Conclusion

We started with understanding why and which customizations can be needed when using any 3rd party UI components library. Then we understood what Angular Material components library provides especially for buttons.

Next, we compared all the approaches mentioned below to add a spinner in Angular Material buttons:

Template interpolation - quick and easy to understand, but reusability is missing
Wrapper component - reusability is achieved, but more complex code and setup required to keep support of default functionalities
Directive - support for default functionalities and reusability, both achieved with less control over template

Then, we understood some thumb rules to prevent our custom styling from breaking with major updates. Next we learned how to effectively modify color, size and typography. And why we shouldn’t modify the size of the Angular Material button.

I have uploaded the code at GitHub, you can also take a look at it on stackblitz.

Angular Material Menu: Nested Menu using Dynamic Data

Dharmen Shah — Tue, 11 Jan 2022 15:07:14 +0000

The Angular Material Menu is a floating panel containing a list of options. In this tutorial, we will learn how we can create nested menus from dynamic data.

We will first learn the basics of Angular Material Menu and how to render a nested menu with a static HTML template.

Then we will understand why and what changes are needed to dynamically render nested menus from data.

Angular Material Menu

<mat-menu> is a floating panel containing a list of options. By itself, the <mat-menu> element does not render anything. The menu is attached to and opened via application of the matMenuTriggerFor directive:

<button mat-button [matMenuTriggerFor]="menu">Menu</button>
<mat-menu #menu="matMenu">
  <button mat-menu-item>Item 1</button>
  <button mat-menu-item>Item 2</button>
</mat-menu>

Static Nested Menu

To render a nested menu with static data, or simply from HTML template, we will have to define the root menu and sub-menus, in addition to setting the [matMenuTriggerFor] on the mat-menu-item that should trigger the sub-menu:

<button mat-button [matMenuTriggerFor]="animals">Animal index</button>

<mat-menu #animals="matMenu">
  <button mat-menu-item [matMenuTriggerFor]="vertebrates">Vertebrates</button>
</mat-menu>

<mat-menu #vertebrates="matMenu">
  <button mat-menu-item [matMenuTriggerFor]="fish">Fishes</button>
  <button mat-menu-item>Amphibians</button>
  <button mat-menu-item>Reptiles</button>
  <button mat-menu-item>Birds</button>
  <button mat-menu-item>Mammals</button>
</mat-menu>

<mat-menu #fish="matMenu">
  <button mat-menu-item>Baikal oilfish</button>
  <button mat-menu-item>Bala shark</button>
  <button mat-menu-item>Ballan wrasse</button>
  <button mat-menu-item>Bamboo shark</button>
  <button mat-menu-item>Banded killifish</button>
</mat-menu>

And the output will be like below:

Dynamic Nested Menu

Building a menu from dynamic data is often needed, especially in business or enterprise applications. For example, loading features based on logged-in user’s permissions. The data may come from a REST API.

We will take an example where items and their children are loaded from a database. And we will render a nested menu for each item which has children.

Database

For the database, we are going to assume the following service. You can connect the actual REST API with this service, too:

import { Injectable } from "@angular/core";
import { delay, of } from "rxjs";

@Injectable({ providedIn: "root" })
export class DynamicDatabase {
  dataMap = new Map<string, string[]>([
    ["Fruits", ["Apple", "Orange", "Banana"]],
    ["Vegetables", ["Tomato", "Potato", "Onion"]],
    ["Apple", ["Fuji", "Macintosh"]],
    ["Onion", ["Yellow", "White", "Purple"]],
    ["Macintosh", ["Yellow", "White", "Purple"]],
  ]);

  rootLevelNodes: string[] = ["Fruits", "Vegetables"];

  getChildren(node: string) {
    // adding delay to mock a REST API call
    return of(this.dataMap.get(node)).pipe(delay(1000));
  }

  isExpandable(node: string): boolean {
    return this.dataMap.has(node);
  }
}

Above service’s code is simple:

dataMap represents data, this could be the actual database
rootLevelNodes represents first nodes to render
getChildren will return the items for a particular node. We will use this to render sub-menu items
isExpandable will return whether there are any children. We will use this to identify whether a sub-menu is needed

Nested Menu

Now understand that, we can’t simply follow the standard HTML template of MatMenu for dynamic data. Below are the reasons:

We can’t load the <mat-menu> until we know that item has children
We can’t attach [matMenuTrigger] to mat-menu-item until <mat-menu> is loaded in the DOM

So, to handle the above problems we will follow the below approach in respective order:

Read node from node list
Check if any node is expandable
1. If yes, then create a sub-menu <mat-menu> with loader and attach it with [matMenuTrigger] in the rendered node’s mat-menu-item
  1. Once the user clicks node, get and render child nodes in sub-menu
  2. For sub-menu’s child-nodes, again follow the same approach and start from step 2
2. If no, then simply create node’s mat-menu-item

Root Component

To achieve the above approach, we will create a app-menu component and use it in app-root:

<!-- src/app/app.component.html -->

<app-menu
  [trigger]="'Food'"
  [data]="initialData"
  [isRootNode]="true"
></app-menu>

// src/app/app.component.ts

import { Component } from "@angular/core";
import { DynamicDatabase } from "./dynamic-database.service";

@Component({
  selector: "app-root",
  templateUrl: "app.component.html",
})
export class AppComponent {
  title = "mat-menu-dynamic-data";
  initialData: string[] = [];
  constructor(private database: DynamicDatabase) {
    this.initialData = this.database.rootLevelNodes.slice();
  }
}

We are reading rootLevelNodes and passing it as data in app-menu.

Menu Component

For the menu, initially we want to show a button, which will trigger a menu:

<!-- src/app/menu/menu.component.html -->

<button mat-button [matMenuTriggerFor]="menu">
  {{ trigger }}
</button>
<mat-menu #menu="matMenu">
  <button mat-menu-item *ngFor="let node of data">{{ node }}</button>
</mat-menu>

And the class looks like this:

// src/app/menu/menu.component.ts

export class MenuComponent {
  @Input() data: string[] = [];
  @Input() trigger = "Trigger";
  @Input() isRootNode = false;
}

Recursion

Now, to render a nested menu, we will just need to handle recursion in this code. And generate the same DOM structure for each nested menu.

So, first we will change the code inside <mat-menu>:

<!-- src/app/menu/menu.component.html -->

<button mat-button [matMenuTriggerFor]="menu">
  {{ trigger }}
</button>
<mat-menu #menu="matMenu">
  <ng-container *ngFor="let node of data; let i = index">
    <button mat-menu-item>
      <app-menu
        [trigger]="node"
        *ngIf="isExpandable(node); else menuItem"
      ></app-menu>
    </button>
    <ng-template #menuItem>
      <button mat-menu-item>{{ node }}</button>
    </ng-template>
  </ng-container>
</mat-menu>

Now, inside the menu, we are checking for each node, if the isExpandable method returns true, we are rendering app-menu again inside it.

isExpandable method will simply call isExpandable from the DynamicDatabase service:

// src/app/menu/menu.component.ts

// ...

export class MenuComponent {

  // ...

  isExpandable(node: string): boolean {
    return this.database.isExpandable(node);
  }
}

Let’s look at the output:

Notice that text is also hoverable inside mat-menu-item. That’s because of the mat-button. When app-menu is rendered inside, we will have to change the directive of the button from mat-button to mat-menu-item, let’s do that:

<!-- src/app/menu/menu.component.html -->

<button *ngIf="isRootNode" mat-button [matMenuTriggerFor]="menu">
  {{ trigger }}
</button>
<button *ngIf="!isRootNode" mat-menu-item [matMenuTriggerFor]="menu">
  {{ trigger }}
</button>
<mat-menu #menu="matMenu">
  <ng-container *ngFor="let node of data; let i = index">
    <button mat-menu-item>
      <app-menu
        [trigger]="node"
        *ngIf="isExpandable(node); else menuItem"
      ></app-menu>
    </button>
    <ng-template #menuItem>
      <button mat-menu-item>{{ node }}</button>
    </ng-template>
  </ng-container>
</mat-menu>

Let’s look at the output now:

It’s rendering the root items fine now, but the sub-menu is blank. Let’s add data in it.

Data

We want to load the data once the menu is rendered and opened. So, we will use the (menuOpened) event to load the data. menuOpened emits the event when the associated menu is opened.

We only want to load the data for non-root items, because for root items, data is coming from the parent component.

<!-- src/app/menu/menu.component.html -->

<button *ngIf="isRootNode" mat-button [matMenuTriggerFor]="menu">
  {{ trigger }}
</button>
<button
  *ngIf="!isRootNode"
  mat-menu-item
  [matMenuTriggerFor]="menu"
  (menuOpened)="getData(trigger)"
>
  {{ trigger }}
</button>

<!-- rest remains same -->

Let’s create a getData method in menu.component.ts:

// src/app/menu/menu.component.ts

// ...
export class MenuComponent {
  // ...

  isLoading = false;
  dataLoaded = false;

  getData(node: string) {
    if (!this.dataLoaded) {
      this.isLoading = true;
      this.database.getChildren(node).subscribe((d) => {
        this.data = d?.slice() || [];
        this.isLoading = false;
        this.dataLoaded = true;
      });
    }
  }
}

With getData, we are creating 2 more flags:

isLoading - Indicates if data is being fetched
dataLoaded - Indicates if data is already loaded and prevents further fetching

Let’s look at the output now:

Notice that data is getting loaded after a particular time, that’s because we have added a delay in DynamicDatabase.getChildren to simulate an API call. And it’s not fetching the data again if it’s already loaded and in that case menu items are rendered instantly.

Loader

The last thing remaining is to show a loader when data is getting fetched. We already have isLoading flag, let’s use that to show <mat-spinner>:

<!-- src/app/menu/menu.component.html -->

<!-- rest remains same -->

<mat-menu #menu="matMenu">
  <button
    mat-menu-item
    *ngIf="isLoading"
    style="display: flex; justify-content: center; align-items: center"
  >
    <mat-spinner mode="indeterminate" diameter="24"></mat-spinner>
  </button>
  <ng-container *ngFor="let node of data; let i = index">
    <!-- rest remains same -->
  </ng-container>
</mat-menu>

Notice that I have added some inline styles so that <mat-spinner> is displayed in the center of mat-menu-item.

Let’s look at the output now:

Summary

We started with a simple example of a menu, where we rendered nested menus using static HTML template.

Then we understood the need for dynamic data in nested menus and the problems to achieve dynamicity with the simple HTML template.

We then created a app-menu component. First we loaded a menu with root items, provided as data input from the parent component.

Then we handled recursion, rendering app-menu inside app-menu, based on isExpandable flag. Next we implemented fetching data based on menuOpened event and finally we displayed a loader while fetching the data.

All the above code is available on GitHub repo: mat-menu-dynamic-data.

Angular Material Theming System: Complete Guide

Dharmen Shah — Wed, 29 Dec 2021 05:57:09 +0000

This guide is written for Angular Material version 13. I am soon going to launch an article series for latest versions. Learn more

In the latest releases of Angular Material, the SASS theming API has been reworked. In this article, we will learn about custom themes, modifying typography and much more using new SASS mixins.

In this article, you will learn what Angular Material Theming is and what are some recent changes to adhere to the new module system of SASS.

Then, we will set up a project with Angular Material. We will then add a custom theme in it and understand some important mixins, core, define-palette, define-light-theme and we will apply custom theme to Angular Material components. And we will also learn how to use a pre-built theme.

After setting up the theme, we will understand typography and also modify it for header tags (<h1>, <h2>, etc.) for the application.

Next, we will create a dark theme using define-dark-theme. We will implement lazy loading for dark theme, so that it only loads when needed.

After adding support for multiple themes, we will learn how to apply Angular Material’s theming to custom components. We will take an example of an alert component and apply themes to it.

We will also learn about how to customize styles of Angular Material components. We will take the example of MatButton and add new variants for it.

And at last, we are going to learn how to update an old code-base with Angular Material version 10 to the latest version, i.e. 13. We will see how to resolve SASS errors and what major changes are made in each release.

Angular Material UI Components

The Angular team builds and maintains both common UI components and tools to help us build our own custom components. @angular/material is Material Design UI components for Angular applications.

Angular Material also provides tools that help developers build their own custom components with common interaction patterns.

Angular Material’s Theming System

In Angular Material, a theme is a collection of color and typography options. Each theme includes three palettes that determine component colors: primary, accent and warn.

Angular Material's theming system comes with a predefined set of rules for color and typography styles. The theming system is based on Google's Material Design specification. You can also customize color and typography styles for components in your application.

SASS Basics

Before moving ahead, It would be great if you have familiarity with SASS basics, including variables, functions, mixins, and use.

New changes of SASS in Angular Material

SASS introduced a new module system, including a migration from @import to @use in 2019. The @use rule loads mixins, functions, and variables from other SASS stylesheets, and combines CSS from multiple stylesheets together. Stylesheets loaded by @use are called "modules".

By switching to @use syntax, we can more easily determine what CSS is unused, and reduce the size of the compiled CSS output. Each module is included only once no matter how many times those styles are loaded.

Angular Material v12 included a migration from @import usage to @use for all imports into the Angular Material SASS styles. They updated their code base for all styles with version 12. You can check out that particular release for more information.

This refactor of the theming API surface is easier to understand and read, helping developers like us take better advantage of this new module system.

Setup project with Angular Material

Note: While writing this article, I used Angular version 13 and the approach described in this article should also work for version 12. For older versions, you can jump to the update guide.

In this section, we are going to learn how to use the new mixins and functions like core-theme, all-components-theme, define-palette, etc. To summarize, below are main tasks which we will be doing:

Create a custom theme
Using a pre-built theme
Modify typography
Create a dark theme
Apply Angular Material’s theme to custom component
Customizing Angular Material Component Styles

Let’s first create a new Angular Project with SASS:

ng new my-app --style=scss --defaults

Use the Angular CLI's installation schematic to set up your Angular Material project by running the following command:

ng add @angular/material

The ng add command will install Angular Material, the Component Dev Kit (CDK), Angular Animations and ask you the following questions to determine which features to include:

Choose a prebuilt theme name, or "custom" for a custom theme: Select Custom
Set up global Angular Material typography styles?: Yes
Set up browser animations for Angular Material?: Yes

You're done! Angular Material is now configured to be used in your application.

Create a 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:

// src/styles.scss

@use "@angular/material" as mat;

@include mat.core();

$my-app-primary: mat.define-palette(mat.$indigo-palette);
$my-app-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
$my-app-warn: mat.define-palette(mat.$red-palette);

$my-app-theme: mat.define-light-theme(
  (
    color: (
      primary: $my-app-primary,
      accent: $my-app-accent,
      warn: $my-app-warn,
    ),
  )
);

@include mat.all-component-themes($my-app-theme);

html,
body {
  height: 100%;
}
body {
  margin: 0;
  font-family: Roboto, "Helvetica Neue", sans-serif;
}

Let’s break the above code into pieces to understand more.

The `core` mixin

@include mat.core();

The first thing in the theme file you will notice is the core mixin. Angular Material defines a mixin named core that includes prerequisite styles for common features used by multiple components, such as ripples. The core mixin must be included exactly once for your application, even if you define multiple themes.

Defining a theme

Angular Material represents a theme as a SASS map that contains your color and typography choices. Colors are defined through a palette.

A palette is a collection of colors representing a portion of color space. Each value in this collection is called a hue. In Material Design, each hue in a palette has an identifier number. These identifier numbers include 50, and then each 100 value between 100 and 900. The numbers order hues within a palette from lightest to darkest. Angular Material represents a palette as a SASS map.

The `define-palette` function

$my-app-primary: mat.define-palette(mat.$indigo-palette);
$my-app-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);
$my-app-warn: mat.define-palette(mat.$red-palette);

To construct a theme, 2 palettes are required: primary and accent, and warn palette is optional.

The define-palette SASS function accepts a color palette, as well as four optional hue numbers. These four hues represent, in order: the "default" hue, a "lighter" hue, a "darker" hue, and a "text" hue.

Components use these hues to choose the most appropriate color for different parts of themselves. For example, MatButton’s theme uses the hues to generate font colors:

// src/material/button/_button-theme.scss
// content reduced for brevity

// Applies a property to an mat-button element for each of the supported palettes.
@mixin _theme-property($theme, $property, $hue) {
  $primary: map.get($theme, primary);
  $accent: map.get($theme, accent);
  $warn: map.get($theme, warn);
  $background: map.get($theme, background);
  $foreground: map.get($theme, foreground);

  &.mat-primary {
    #{$property}: theming.get-color-from-palette($primary, $hue);
  }
  &.mat-accent {
    #{$property}: theming.get-color-from-palette($accent, $hue);
  }
  &.mat-warn {
    #{$property}: theming.get-color-from-palette($warn, $hue);
  }

  &.mat-primary,
  &.mat-accent,
  &.mat-warn,
  &.mat-button-disabled {
    &.mat-button-disabled {
      $palette: if($property == "color", $foreground, $background);
      #{$property}: theming.get-color-from-palette($palette, disabled-button);
    }
  }
}

@mixin color($config-or-theme) {
  $config: theming.get-color-config($config-or-theme);
  $foreground: map.get($config, foreground);

  .mat-button,
  .mat-icon-button,
  .mat-stroked-button {
    @include _theme-property($config, "color", text);
  }
}

In our example, we have used predefined palettes, i.e. $indigo-palette, $pink-palette and $red-palette. You can check out other palettes at the Angular Material GitHub repo’s file:

// src/material/core/theming/_palette.scss
// content reduced for brevity

$red-palette: (
  50: #ffebee,
  100: #ffcdd2,
  200: #ef9a9a,
  300: #e57373,
  // ...
  contrast: (
    50: $dark-primary-text,
    100: $dark-primary-text,
    200: $dark-primary-text,
    300: $dark-primary-text,
    // ...
  )
);

$pink-palette: (
  50: #fce4ec,
  100: #f8bbd0,
  200: #f48fb1,
  300: #f06292,
  // ...
  contrast: (
    50: $dark-primary-text,
    100: $dark-primary-text,
    200: $dark-primary-text,
    300: $dark-primary-text,
    // ...
  )
);

Create your own palette

You can also create your own palettes by defining a SASS map like below:

$indigo-palette: (
 50: #e8eaf6,
 100: #c5cae9,
 200: #9fa8da,
 300: #7986cb,
 // ... continues to 900
 contrast: (
   50: rgba(black, 0.87),
   100: rgba(black, 0.87),
   200: rgba(black, 0.87),
   300: white,
   // ... continues to 900
 )
);

The `define-light-theme` function

$my-app-theme: mat.define-light-theme(
  (
    color: (
      primary: $my-app-primary,
      accent: $my-app-accent,
      warn: $my-app-warn,
    ),
  )
);

You can construct a theme by calling either define-light-theme or define-dark-theme with the result from define-palette. The choice of a light versus a dark theme determines the background and foreground colors used throughout the components.

Applying a theme to components

@include mat.all-component-themes($my-app-theme);

Angular Material offers a "theme" mixin that emits styles for both color and typography and It’s the all-component-themes mixin.

You can check the source file: src/material/core/theming/_all-theme.scss to see the mixin all-component-themes:

// src/material/core/theming/_all-theme.scss

@mixin all-component-themes($theme-or-color-config) {
  $dedupe-key: 'angular-material-theme';
  @include theming.private-check-duplicate-theme-styles($theme-or-color-config, $dedupe-key) {
    @include core-theme.theme($theme-or-color-config);
    @include autocomplete-theme.theme($theme-or-color-config);
    @include badge-theme.theme($theme-or-color-config);
    @include bottom-sheet-theme.theme($theme-or-color-config);
    @include button-theme.theme($theme-or-color-config);
    // other material components' themes...
  }
}

Additionally, there is a "color" mixin that emits all components' color styles and a "typography" mixin that emits all components’ typography styles. They are all-component-colors and all-component-typographies mixins.

The all-component-colors mixin is present atsrc/material/core/color/_all-color.scss has:

// src/material/core/color/_all-color.scss

@mixin all-component-colors($config-or-theme) {
  $config: if(theming.private-is-theme-object($config-or-theme),
      theming.get-color-config($config-or-theme), $config-or-theme);

  @include all-theme.all-component-themes((
    color: $config,
    typography: null,
    density: null,
  ));
}

And all-components-typography mixin is present at src/material/core/typography/_all-typography.scss:

// src/material/core/typography/_all-typography.scss

@mixin all-component-typographies($config-or-theme: null) {
  $config: if(theming.private-is-theme-object($config-or-theme),
      theming.get-typography-config($config-or-theme), $config-or-theme);

  @include badge-theme.typography($config);
  @include typography.typography-hierarchy($config);
  @include autocomplete-theme.typography($config);
  @include bottom-sheet-theme.typography($config);
  @include button-theme.typography($config);
  // other components' typographies
}

These mixins emit styles for all 35+ components in Angular Material. This will produce unnecessary CSS, except when your application is using every single component from the library. Let’s look at the styles size after the build command and then I’ll show you how to reduce it:

Include only used components’ themes

Just like all-component-colors, all-component-typographies and all-component-themes, each Angular Material component has a color, a typography and a theme mixin.

You can checkout MatButton’s mixins at src/material/button/_button-theme.scss:

// src/material/button/_button-theme.scss
// content reduced for brevity

@mixin color($config-or-theme) {
  $config: theming.get-color-config($config-or-theme);
  $primary: map.get($config, primary);
  $accent: map.get($config, accent);
  $warn: map.get($config, warn);
  // sets up color for buttons
}

@mixin typography($config-or-theme) {
  $config: typography.private-typography-to-2014-config(
      theming.get-typography-config($config-or-theme));
  .mat-button, .mat-raised-button, .mat-icon-button, .mat-stroked-button,
  .mat-flat-button, .mat-fab, .mat-mini-fab {
    font: {
      family: typography-utils.font-family($config, button);
      size: typography-utils.font-size($config, button);
      weight: typography-utils.font-weight($config, button);
    }
  }
}

@mixin theme($theme-or-color-config) {
  $theme: theming.private-legacy-get-theme($theme-or-color-config);
  @include theming.private-check-duplicate-theme-styles($theme, 'mat-button') {
    $color: theming.get-color-config($theme);
    $typography: theming.get-typography-config($theme);

    @if $color != null {
      @include color($color);
    }
    @if $typography != null {
      @include typography($typography);
    }
  }
}

We can apply the styles for each of the components used in the application by including each of their theme SASS mixins.

First, we will remove all-component-themes from styles.scss and instead, add core-theme:

// @include mat.all-component-themes($my-app-theme); <-- removed
@include mat.core-theme($my-app-theme);

core-theme emits theme-dependent styles for common features used across multiple components, like ripples.

Next, we need to add component related styles. In this example, we are only going to use MatButton, so we will add button-theme:

@include mat.button-theme($my-app-theme);

You can add other components’ theme’s in the same way. But, core-theme is only needed once per theme. Let’s look at the styles size now after build.

Notice how using only the needed components’ themes reduces the style's size. In our case, it was 72.31 kB earlier and it’s reduced to 23.52 kB, which is almost 58% less.

For better code management, we will move theme related code into styles/themes/_light.scss:

// src/styles/themes/_light.scss

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

$my-app-light-primary: mat.define-palette(mat.$indigo-palette);
$my-app-light-accent: mat.define-palette(mat.$pink-palette, A200, A100, A400);

$my-app-light-warn: mat.define-palette(mat.$red-palette);

$my-app-light-theme: mat.define-light-theme(
  (
    color: (
      primary: $my-app-light-primary,
      accent: $my-app-light-accent,
      warn: $my-app-light-warn,
    ),
  )
);

And use the same in styles.scss:

// styles.scss

@use "@angular/material" as mat;

@use "./styles/themes/light";

@include mat.core();

@include mat.core-theme(light.$my-app-light-theme);
@include mat.button-theme(light.$my-app-light-theme);

html,
body {
  height: 100%;
}
body {
  margin: 0;
  font-family: Roboto, "Helvetica Neue", sans-serif;
}

Output after creating custom theme

Let’s add a [mat-raised-button] in application and see how it looks:

<button mat-raised-button color="primary">Raised</button>
<button mat-raised-button color="accent">Accent</button>
<button mat-raised-button color="warn">Warn</button>

And the output should look like below:

Using a pre-built theme

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:

Theme	Light or dark?	Palettes (primary, accent, warn)
deeppurple-amber.css	Light	deep-purple, amber, red
indigo-pink.css	Light	indigo, pink, red
pink-bluegray.css	Dark	pink, bluegray, red
purple-green.css	Dark	purple, green, red

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

"styles": [
    "./node_modules/@angular/material/prebuilt-themes/indigo-pink.css",
    // other styles
],

Modify typography

Typography is a way of arranging type to make text legible, readable, and appealing when displayed. Angular Material's theming system supports customizing the typography settings for the library's components. Additionally, Angular Material provides APIs for applying typography styles to elements in your own application.

When we installed Angular Material through schematics, it set up the font asset for us in index.html:

<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">

And to support Roboto, it also added some global styles in styles.scss:

body {
  font-family: Roboto, "Helvetica Neue", sans-serif;
}

Typography level

In the Material theme, each set of typography is categorised in levels based on which part of the application's structure it corresponds to, such as a header. You can learn more about it at typography levels from the 2014 version of the Material Design specification.

Name	CSS Class	Native Element	Description
display-4	`.mat-display-4`	None	112px, one-off header, usually at the top of the page (e.g. a hero header).
display-3	`.mat-display-3`	None	56px, one-off header, usually at the top of the page (e.g. a hero header).
display-2	`.mat-display-2`	None	45px, one-off header, usually at the top of the page (e.g. a hero header).
display-1	`.mat-display-1`	None	34px, one-off header, usually at the top of the page (e.g. a hero header).
headline	`.mat-h1` or `.mat-headline`	`<h1>`	Section heading corresponding to the `<h1>` tag.
title	`.mat-h2` or `.mat-title`	`<h2>`	Section heading corresponding to the `<h2>` tag.
subheading-2	`.mat-h3` or `.mat-subheading-2`	`<h3>`	Section heading corresponding to the `<h3>` tag.
subheading-1	`.mat-h4` or `.mat-subheading-1`	`<h4>`	Section heading corresponding to the `<h4>` tag.
--	`.mat-h5`	`<h5>`	--
--	`.mat-h6`	`<h6>`	--
body-1	`.mat-body` or `.mat-body-1`	Body text	Base body text.
body-2	`.mat-body-strong` or `.mat-body-2`	None	Bolder body text.
caption	`.mat-small` or `.mat-caption`	None	Smaller body and hint text.
button	--	--	Buttons and anchors.
input	--	--	Form input fields.

Define a level

You can define a typography level with the define-typography-config SASS function. This function accepts, in order, CSS values for font-size, line-height, font-weight, font-family, and letter-spacing. You can also specify the parameters by name, as demonstrated in the example below.

@use '@angular/material' as mat;

$my-custom-level: mat.define-typography-level(
  $font-family: Roboto,
  $font-weight: 400,
  $font-size: 1rem,
  $line-height: 1,
  $letter-spacing: normal,
);

Typography config

Angular Material handles all those levels using typography config. Angular Material represents this config as a SASS map.This map contains the styles for each level, keyed by name. You can create a typography config with the define-typography-config SASS function. Every parameter for define-typography-config is optional; the styles for a level will default to Material Design's baseline if unspecified.

For this example, we will change the typography of headings and we will use Work Sans as font-family. Let’s see how.

Including font assets

First, we will add the font at the bottom of <head> in index.html:

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Work+Sans:wght@300;400;500&display=swap">

Heading font-family SASS variable

Next, create a file styles/typography/_config.scss and create a variable in it:

// src/styles/typography/_config.scss

$heading-font-family: "'Work Sans', sans-serif";

Create config

Now it’s time to create the config using define-typography-config in styles/typography/_config.scss:

$my-app-typography: mat.define-typography-config(
  $display-4: mat.define-typography-level(112px, $font-family: $heading-font-family),
  $display-3: mat.define-typography-level(56px, $font-family: $heading-font-family),
  $display-2: mat.define-typography-level(45px, $font-family: $heading-font-family),
  $display-1: mat.define-typography-level(34px, $font-family: $heading-font-family),
  $headline: mat.define-typography-level(24px, $font-family: $heading-font-family),
  $title: mat.define-typography-level(20px, $font-family: $heading-font-family),
);

To customize component typography for the entire application, we will pass the custom typography config to the core mixin in styles.scss:

// src/styles.scss

@use "@angular/material" as mat;

@use "./styles/themes/light";
@use "./styles/typography/config" as typography;

@include mat.core(typography.$my-app-typography);

// rest remains same

Passing the typography config to core mixin will apply specified values to all Angular Material components. If a config is not specified, core will emit the default Material Design typography styles.

Theme specific typography

In addition to the core mixin, we can specify your typography config when including any theme mixin, like below:

$custom-theme: mat.define-light-theme((
   color: (
     primary: $custom-primary,
     accent: $custom-accent,
   ),
   typography: $custom-typography,
  ));

Because the core mixin always emits typography styles, specifying a typography config to a theme mixin results in duplicate typography CSS. You should only provide a typography config when applying your theme if you need to specify multiple typography styles that are conditionally applied based on your application's behavior.

Using typography styles in your application

Angular Material's native elements’ typography works if content is wrapped within the '.mat-typographyCSS class. If you check theindex.htmlfile,mat-typographyclass is added to the

tag. It was done when we ranng add @angular/material`.

If you don’t want to wrap the whole application in a mat-typography class, you can also use individual classes listed in the levels table.

Output after modifying the typography

Let’s temporarily modify the content of <body> in index.html:

html <body>

Top header (Material Typography doesn't apply here)

<!-- This paragraph will be styled as `body-1` via the `.mat-body` CSS class applied -->
<p class="mat-body">Introductory text</p>

<div class="mat-typography">
  <!-- This header will be styled as `title` because it is inside `.mat-typography` -->
  <h2>Inner header</h2>

  <!-- This paragraph will be styled as `body-1` because it is inside `.mat-typography` -->
  <p>Some inner text</p>
  <app-root></app-root>
</div>

If you look at the output, you will get an idea how typography works:

After modifying typography, below is the content of src/styles/typography/_config.scss:

`scss
// src/styles/typography/_config.scss

@use "@angular/material" as mat;

$heading-font-family: "'Work Sans', sans-serif";
$my-app-typography: mat.define-typography-config(
$display-4:
mat.define-typography-level(112px, $font-family: $heading-font-family),
$display-3:
mat.define-typography-level(56px, $font-family: $heading-font-family),
$display-2:
mat.define-typography-level(45px, $font-family: $heading-font-family),
$display-1:
mat.define-typography-level(34px, $font-family: $heading-font-family),
$headline:
mat.define-typography-level(24px, $font-family: $heading-font-family),
$title: mat.define-typography-level(20px, $font-family: $heading-font-family),
);
`

And below is the content of style.scss:

`scss
// src/styles.scss

@use "@angular/material" as mat;

@use "./styles/themes/light";
@use "./styles/typography/config" as typography;

@include mat.core(typography.$my-app-typography);

@include mat.core-theme(light.$my-app-light-theme);
@include mat.button-theme(light.$my-app-light-theme);

html,
body {
height: 100%;
}
body {
margin: 0;
font-family: Roboto, "Helvetica Neue", sans-serif;
}
`

Create a dark theme

Now we will add a dark theme in the application. Create a new file called dark.scss in the styles/themes folder with the following content:

`scss
// src/styles/themes/dark.scss

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

@use "../typography/config" as typography;
@use "../components";

$my-app-dark-primary: mat.define-palette(mat.$blue-grey-palette);
$my-app-dark-accent: mat.define-palette(mat.$amber-palette, A200, A100, A400);
$my-app-dark-warn: mat.define-palette(mat.$deep-orange-palette);
$my-app-dark-theme: mat.define-dark-theme(
(
color: (
primary: $my-app-dark-primary,
accent: $my-app-dark-accent,
warn: $my-app-dark-warn,
),
)
);

.dark-theme {
@include mat.core-color($my-app-dark-theme);
@include mat.button-color($my-app-dark-theme);
}
`

Notice that we are using a class selector .dark-theme to render a dark theme.

Avoiding duplicated theming styles

While creating dark-theme, instead of core-theme and button-theme, which we used in the original theme, we are using core-color and button-color. The reason behind that is we only want to change colors in dark-theme and every other style should remain the same. If we use theme mixins, it would generate all the styles again, which are not required.

Changes for background and font color

To complete the theme setup for background and font color, we will need to add class mat-app-background to the <body> tag in index.html:

html <body class="mat-typography mat-app-background"> <app-root></app-root> </body>

Lazy load dark theme

For our application, dark-theme is an additional theme and can be loaded based on user preferences. So, instead of making it part of the default application, we will lazy load it.

Let’s make changes for that in the project’s angular.json:

json "styles": [ "src/styles.scss", { "input": "src/styles/themes/dark.scss", "bundleName": "dark-theme", "inject": false } ],

You can learn more about lazy loading stylesheets at: How to exclude stylesheets from the bundle and lazy load them in Angular?

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

`typescript
// style-manager.service.ts

import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class StyleManager {
isDark = false;

toggleDarkTheme() {
if (this.isDark) {
this.removeStyle('dark-theme');
document.body.classList.remove('dark-theme');
this.isDark = false;
} else {
const href = 'dark-theme.css';
getLinkElementForKey('dark-theme').setAttribute('href', href);
document.body.classList.add('dark-theme');
this.isDark = true;
}
}

removeStyle(key: string) {
const existingLinkElement = getExistingLinkElementByKey(key);
if (existingLinkElement) {
document.head.removeChild(existingLinkElement);
}
}
}

function getLinkElementForKey(key: string) {
return getExistingLinkElementByKey(key) || createLinkElementWithKey(key);
}

function getExistingLinkElementByKey(key: string) {
return document.head.querySelector(
link[rel="stylesheet"].${getClassNameForKey(key)}
);
}

function createLinkElementWithKey(key: string) {
const linkEl = document.createElement('link');
linkEl.setAttribute('rel', 'stylesheet');
linkEl.classList.add(getClassNameForKey(key));
document.head.appendChild(linkEl);
return linkEl;
}

function getClassNameForKey(key: string) {
return style-manager-${key};
}
`

Above is a very opinionated approach, you can change it as per your need.

Output after creating a dark-theme

Now, let’s utilize the above service in app.component.ts:

`typescript
// src/app/app.component.ts

import { Component } from '@angular/core';
import { StyleManager } from './shared/services/style-manager.service';

@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss'],
})
export class AppComponent {
title = 'my-app';
isDark = this.styleManager.isDark;

constructor(private styleManager: StyleManager) {}

toggleDarkTheme() {
this.styleManager.toggleDarkTheme();
this.isDark = !this.isDark;
}
}
`

Next, we will add a button to toggle dark and light themes in app.component.html:

`html

Angular Material Theming System: Complete Guide

{{ isDark ? "dark_mode" : "light_mode" }} Raised Accent Warn

Let’s look at the output now:

Notice that when we change theme, it changes colors and background colors of buttons and text. And also notice that dark-theme.css is only included when the user switches to the dark theme.

Apply Angular Material’s theme to custom component

Let’s assume that there is an alert component with the template below:

`html

Success
Success Stroked
Success Flat
Success Raised

check_circle

check_circle

check_circle

Info
Info Stroked
Info Flat
Info Raised

info

info

info

`

Let’s take a look at output now:

Updating old project to latest version of Angular Material

If your current project uses Angular Material older than version 12 and wants to update to version 13, then follow this section, else you can jump to the summary.

For this example, we are going to take code from my series of “Custom Theme for Angular Material Components Series”. The code is available at indepth-theming-material-components.

If you run ng version inside the project's folder, you will notice that version 10.1 is used. And we want to upgrade it to version 13.

Angular Update Guide

We are going to follow guidelines from the Angular Update Guide. Angular CLI does not support migrating across multiple major versions at once. So we will migrate each major version individually.

Open up the terminal in the project's folder and run the commands below. After each command you will have to commit your changes, otherwise Angular CLI will not allow you to proceed further.

While running any of the commands below, if you face any error like Could not resolve dependency or Conflicting peer dependency, do the following:

Revert the changes of package.json
Install dependencies again with npm i
Run the update command with --force

Version 10 to 11

Update Angular to version 11

bash npx @angular/cli@11 update @angular/core@11 @angular/cli@11

Update Angular Material to version 11

bash npx @angular/cli@11 update @angular/material@11

With this, we have updated the project to version 11. Check once by running npm start. Now, we will upgrade the project to version 12.

Version 11 to 12

Update Angular to version 12

bash npx @angular/cli@12 update @angular/core@12 @angular/cli@12

Update Angular Material to version 12

bash npx @angular/cli@12 update @angular/material@12

Changes of version 12

With the above command, you will see many changes, let’s understand what’s changed.

Migration from `@import` to `@use`

The first major change you will notice is migration from @import to @use. So in all .scss files, below @import

scss @import "~@angular/material/theming";

is changed to below @use:

scss @use "~@angular/material" as mat;

The @use rule loads mixins, functions, and variables from other SASS stylesheets, and combines CSS from multiple stylesheets together. Stylesheets loaded by @use are called "modules".

The SASS team discourages the continued use of the @import rule. SASS will gradually phase it out over the next few years, and eventually remove it from the language entirely

API refactors

To adhere to the above-mentioned module system, many APIs are also reworked. And they have been refactored for better developer experience. For example, mat-get-color-config is changed to mat.get-color-config. mat-color is changed to mat.get-color-from-palette.

Fix errors after update

Now if you try to run the project, it will throw errors. Let’s resolve those errors one by one.

Value isn’t a valid CSS value

The first error you will see is at line 7 of sidenav.component.scss-theme.scss:

bash 7 │ $config: mat-get-color-config($config-or-theme); │ ^^^^^^^^^^^^^^^^

To fix that, we will change mat-get-color-config to mat.get-color-config. And make the same change in dialog.component.scss-theme.scss:

scss $config: mat.get-color-config($config-or-theme);

Undefined mixin

The next error you will see is at line 28:

bash 28 │ @include _mat-toolbar-color($val); │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Above error is coming because within Angular Material version 12, components’ color mixins are refactored. And we can’t simply use the mixin any more. So, instead of using MatToolbar’s color mixin, we will use it’s SASS code. So change above line with below 2 lines in both, sidenav.component.scss-theme.scss and dialog.component.scss-theme.scss files:

scss background-color: mat.get-color-from-palette($val); color: mat.get-color-from-palette($val, default-contrast);

Now your project should run fine.

Adhere to latest SASS changes

As per the latest SASS changes, map module functions should be used in the new module system. For that, first we will use the SASS:map module using the @use rule:

scss @use "sass:map";

And then, simply change all map-get to map.get in both, sidenav.component.scss-theme.scss and dialog.component.scss-theme.scss files:

scss $primary: map.get($config, primary); $accent: map.get($config, accent); $warn: map.get($config, warn); $foreground: map.get($config, foreground); $background: map.get($config, background);

Version 12 to 13

Update Angular to version 13

bash npx @angular/cli@13 update @angular/core@13 @angular/cli@13

Update Angular Material to version 12

bash npx @angular/cli@13 update @angular/material@13

Removal of tilde

After the above command, except dependencies, one major change you will notice in all .scss files is the removal of ~ (tilde) from @use "~@angular/material" as mat;.

The reason behind that is SASS-loader has deprecated the usage of ~ and it’s recommended that it’s removed from code.

Why remove it?

The loader will first try to resolve @use as a relative path. If it cannot be resolved, then the loader will try to resolve @use inside node_modules.

Summary

In this article, we first learned about what Angular Material Theming is and it is based on Google's Material Design specification. And then we understood that with Angular Material version 12, @import rule migrated to @use and SASS APIs were refactored for better developer experience.

We started with a blank project and added Angular Material. Next, we understood the core mixin, define-palette function, palettes and define-light-theme function and we created a custom theme. And then we applied our custom theme to first all components using all-components-theme and at last we optimized it to use only core-theme and button-theme and reduced final styles size.

We also learned how to use a pre-built theme by adding the theme's stylesheet path in the styles array of angular.json. For example, we can add ./node_modules/@angular/material/prebuilt-themes/indigo-pink.css to use the indigo-pink theme in our application.

Then we started with typography. We first understood typography levels and how to create one using define-typography-level. Next, we learned that Angular Material handles all those levels using typography config, and Angular Material represents this configuration as a SASS map. We created a custom config using define-typography-config and applied it to core mixin so that custom typography is applied to the whole application.

Next we created a dark theme in a separate file themes/dark-theme.scss. Then we used only color mixins, i.e. core-color and button-color, and not theme mixing to avoid duplicate style generation. And at last, we made changes in angular.json so that dark theme is loaded on demand only when needed.

Then we followed a step-by-step process to add support for Angular Material’s Theming system to custom components.

And at last, we learned about how to customise Angular Material’s button component, i.e. MatButton. In this, we mainly followed the approach from its source code and we added two new variants to it: success and info.

The project which we created in this article is available on GitHub repo at angular-material-theming-system-complete-guide.

With the new system, we also looked at how to update older Angular Material versions to the latest one by taking examples from one of the old projects.

Credits

While writing this article I took references from Angular Material Guides.

DEV Community: Dharmen Shah

How to handle browser storage in Angular SSR?

1. A service to use browser storage for Browser

2. Provide service to whole browser application

3. A service to use browser storage for Server

4. Provide service to whole server application

Practical guide for loading SVG icons with Angular Material

MatIconRegistry

addSvgIcon

addSvgIconInNamespace

addSvgIconLiteral

addSvgIconLiteralInNamespace

addSvgIconResolver

addSvgIconSet

Summary

Live Playground

Create size variant for Angular Material Button

How to change size

Density

Typography

Creating a size variant

1. Create a file for size

2. Import size file

Conclusion

Course Announcement: A complete theming guide to Angular Material Components

🚀 A complete theming guide to Angular Material Components

What’s included?

Toggle dark theme in Angular Material

Save some bytes when using multiple themes in angular material components

Dharmen Shah for Angular Material Dev ・ Sep 17

Modify colors of Angular Material Button

Save some bytes when using multiple themes in angular material components

Creating a custom form field control group using Angular Material

Introduction

How to build custom form group using Angular Material

Basic Address Form Component

Providing our component as a MatFormFieldControl

Implementing the methods and properties of MatFormFieldControl

value

stateChanges

id

placeholder

ngControl and ControlValueAccessor

focused

empty

shouldLabelFloat

required

disabled

errorState

controlType

setDescribedByIds(ids: string[])

onContainerClick(event: MouseEvent)

Improving accessibility

Trying it out

InDepth Guide for Creating Nested and Reusable Forms

Introduction

How to create and use FormGroup

How to create nested form-groups

How to use child component with nested form-group

How to create reusable form with Composite ControlValueAccessor

ControlValueAccessor

Composite ControlValueAccessors

Reusable Form

writeValue

registerOnChange

registerOnTouched

setDisabledState

Validation

validate

Multiple instances

Conclusion

InDepth Guide for Customizing Angular Material Button

Introduction

Angular Material Button

How to change styles

Thumb rules

Color

Shape

Other styles changes

Size

`MatIconRegistry`

`addSvgIcon`

`addSvgIconInNamespace`

`addSvgIconLiteral`

`addSvgIconLiteralInNamespace`

`addSvgIconResolver`

`addSvgIconSet`

Providing our component as a `MatFormFieldControl`

Implementing the methods and properties of `MatFormFieldControl`

`value`

`stateChanges`

`id`

`placeholder`

`ngControl` and `ControlValueAccessor`

`focused`

`empty`

`shouldLabelFloat`

`required`

`disabled`

`errorState`

`controlType`

`setDescribedByIds(ids: string[])`

`onContainerClick(event: MouseEvent)`

How to create reusable form with Composite `ControlValueAccessor`

How to add `MatProgressSpinner`

The `core` mixin

The `define-palette` function

The `define-light-theme` function

Migration from `@import` to `@use`