UPGRADE to Angular Material v15 with MDC

Mohd Irshad — Thu, 16 Jan 2025 17:32:29 +0000

Upgrading Angular Material from Version 14 to 15: A Step-by-Step Guide

If you're planning to upgrade Angular Material from version 14 to version 15, follow these essential steps to prepare and execute the migration. Before upgrading, some adjustments in your existing codebase are necessary to avoid breaking changes.

Preparatory Steps in Angular Material v14
1. Update floatLabel Property
The floatLabel="never" value is deprecated in Angular Material v15. Replace it with a valid value such as floatLabel="always" or the default floatLabel="auto".

Before:

<mat-form-field class="text-class" floatLabel="never">
  <input/>
</mat-form-field>

After:

<mat-form-field class="text-class" floatLabel="always">
  <input/>
</mat-form-field>

2. Update appearance Property
The appearance="standard" value is no longer supported. Replace it with either appearance="fill" or appearance="outline".
Before:

<mat-form-field class="field-body" appearance="standard" floatLabel="always">
  <input/>
</mat-form-field>

After:

<mat-form-field class="field-body" appearance="fill" floatLabel="always">
  <input/>
</mat-form-field>

3. Update mat-tab-nav-bar to Use tabPanel
Before:

<div class="nav">
  <nav mat-tab-nav-bar>
    <ng-container *ngFor="let item of items">
      <span>{{ item }}</span>
    </ng-container>
  </nav>
</div>

After:

<div class="nav">
  <nav mat-tab-nav-bar [tabPanel]="tabPanel">
    <ng-container *ngFor="let item of items">
      <span>{{ item }}</span>
    </ng-container>
  </nav>
</div>
<mat-tab-nav-panel #tabPanel>
  <router-outlet></router-outlet>
</mat-tab-nav-panel>

By completing these three steps, you can avoid breaking template errors when upgrading to Angular Material v15.

Upgrade Angular Material to v15
Run the following command to upgrade Angular Material to version 15:

npm install @angular/material@^15.2.9

update other packages too in your application as required.

Migrate to MDC-Based Components
Angular Material v15 officially transitions to MDC-based components, which adhere strictly to Material Design specifications. Non-MDC components are deprecated and will no longer receive updates or fixes. To migrate:
1. Run the Migration Tool
The Angular CLI provides a schematic to migrate your project to MDC-based components:

ng generate @angular/material:mdc-migration

2. Update Your Theme
MDC-based components use an updated theming API. Replace your old theme configuration with the new structure:

Before (v14 or earlier):

$custom-typography: mat.define-typography-config(
  $font-family: 'Noto Sans',
  $body-1: mat.define-typography-level($font-size-xs, $line-height-xs, $font-weight-regular),
  $body-2: mat.define-typography-level($font-size-xs, $line-height-xs, $font-weight-bold),
  $caption: mat.define-typography-level($font-size-xxs, $line-height-xxs, $font-weight-regular),
  $button: mat.define-typography-level($font-size-xs, $line-height-xs, $font-weight-regular)
);

@include mat.core($custom-typography);

$theme-primary: mat.define-palette($custom-pink);
$theme-accent: mat.define-palette($custom-wine);
$theme-warn: mat.define-palette(mat.$red-palette);

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

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

After (v15 with MDC):

$custom-typography: mat.define-typography-config(
  $font-family: 'Noto Sans',
  $body-1: mat.define-typography-level($font-size-xs, $line-height-xs, $font-weight-regular),
  $body-2: mat.define-typography-level($font-size-xs, $line-height-xs, $font-weight-bold),
  $caption: mat.define-typography-level($font-size-xxs, $line-height-xxs, $font-weight-regular),
  $button: mat.define-typography-level($font-size-xs, $line-height-xs, $font-weight-regular)
);

@include mat.core();

$theme-primary: mat.define-palette($custom-pink);
$theme-accent: mat.define-palette($custom-wine);
$theme-warn: mat.define-palette(mat.$red-palette);

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

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

Post-Migration Adjustments
The migration tool (ng generate @angular/material:mdc-migration) does not update all class names automatically. You'll need to manually update class names in your styles where necessary.

Example:
Pre-v15: mat-form-field-flex
Post-v15 with MDC: mat-mdc-form-field-flex
To identify required changes, look for // TODO (mdc-migration) comments in your SCSS files.

Why Migrate to MDC-Based Components?
Future-Proof: Non-MDC components are no longer maintained.
Material Design Compliance: MDC-based components adhere strictly to Material Design guidelines.
Improved Performance: MDC components include accessibility improvements, better animations, and updated styles.
Avoid Forced Migration Later: Future Angular Material versions will remove non-MDC components entirely.
For a comprehensive list of changes, consult the official Angular Material documentation.

By following these steps, you can seamlessly upgrade to Angular Material v15 and ensure your application is ready for future updates.

DEV Community: Mohd Irshad

UPGRADE to Angular Material v15 with MDC