Solving Style Issues: Angular Material MDC Migration Guide

Angular Material MDC Migration

After migrating to the latest Material Design Components (MDC), many projects, including ours, have encountered style-related issues. In this write-up, we will explain how we resolved them.

We acknowledge that the core problem lies in creating components based on Material Components and modifying them to suit our specific use cases.

Here are the steps we followed to migrate from Material Components to Material MDC Components.

Note: You can Choose legacy components, but anyways we decided to go with MDC Migration.

Steps for MDC Migration

Upgrade Angular, Material, and run the mdc-migration script provided by the Material team.

You can either copy this code and create a batch file to run it or execute each step individually.

@ECHO OFF
call npm i typescript@4.8.x --force
call npm i zone.js @angular/flex-layout@15.0.0-beta.42 @angular-eslint/builder@15.x @angular-eslint/eslint-plugin@15.x @angular-eslint/eslint-plugin-template@15.x @angular-eslint/schematics@15.x @angular-eslint/template-parser@15.x  --force
call npx ng update @angular/core@15 @angular/cli@15 --allow-dirty --force
call npx ng update @angular/material@15 --allow-dirty --force
call npx ng generate @angular/material:mdc-migration
PAUSE

Update your theme file

@use '@angular/material' as mat;
$ec--mat-typography: mat.define-typography-config(
    $font-family: $aal-font-family,
    $headline-4: mat.define-typography-level($aal-font-h1...),
    $headline-3: mat.define-typography-level($aal-font-h2...),
    ...more settings
);
/* This is the new way of defining a theme from Angular 15 */
$ec--mat-light-theme: mat.define-light-theme((
  color: (
      primary: $aal--mat-primary-color,
      accent: $aal--mat-accent-color,
      warn: $aal--mat-warn-color
  ),
  typography: $aal--mat-typography,
  density: -1, // you can experiment with densities that suit your application
));

@include mat.typography-hierarchy($ec--mat-typography);
@include mat.core();
/**
  It is important to include all component themes in the body
 */
body {
    @include mat.all-component-themes($aal--mat-light-theme);
    @include mat.button-density(-2); // these densities make more sense for my project, feel free to experiment
    @include mat.icon-button-density(-2); // these densities make more sense for my project, feel free to experiment
}

Search throughout your application and replace the following classes, if you have used them.

Here is a comprehensive list of classes that are not automatically migrated by "ng generate @angular/material:mdc-migration"

Component	Old Class	New Class
mat-tab	mat-tab-label-active	mdc-tab--active
	mat-tab-label-content	mdc-tab__content
	mat-tab-label-container	mat-mdc-tab-label-container
	mat-tab-list	mat-mdc-tab-list
	mat-tab-body-wrapper	mat-mdc-tab-body-wrapper
	mat-tab-label	mat-mdc-tab
	mat-tab-header-pagination-controls-enabled	mat-mdc-tab-header-pagination-controls-enabled
	mat-tab-header-pagination	mat-mdc-tab-header-pagination
	mat-tab-labels	mat-mdc-tab-labels
mat-chip	mat-chip-list	mat-mdc-chip-list
	mat-chip-list-wrapper	mat-chip-list-wrapper
mat-checkbox	mat-checkbox-frame	mdc-checkbox__checkmark
	mat-checkbox-label	mdc-label
	mat-checkbox-checked	mat-mdc-checkbox-checked
	mat-checkbox-label	mdc-label
	mat-checkbox-layout	-
mat-button	mat-button-focus-overlay	mat-mdc-focus-indicator
mat-radio	mat-radio-outer-circle	mdc-radio__outer-circle
	mat-radio-inner-circle	mdc-radio__inner-circle
	mat-radio-checked	mat-mdc-radio-checked
	mat-radio-label-content	mdc-label
	mat-radio-label	mdc -label
mat-progress-bar	mat-progress-bar-buffer	mdc-linear-progress__buffer
mat-form-field	mat-form-field-flex	mat-mdc-form-field-flex
	mat-form-field-wrapper	mat-mdc-text-field-wrapper
	mat-form-field-underline	mdc-line-ripple
	mat-form-field-subscript-wrapper	mat-mdc-form-field-subscript-wrapper
	mat-form-field-prefix	mat-mdc-form-field-text-prefix
	mat-form-field-suffix	mat-mdc-form-field-text-suffix
	mat-form-field-infix	mat-mdc-form-text-infix
	mat-form-field-label	mat-mdc-floating-label
mat-dialog	mat-dialog-container	mdc-dialog__container
	mat-dialog-content	mat-mdc-dialog-content
No Change
	mat-button-toggle
	mat-button-toggle-checked
	mat-button-toggle-disabled
	mat-button-toggle-focus-overlay

Final Thoughts

It is highly likely that this setup may not be entirely comprehensive and depends on your project's settings. However, please feel free to add comments about your upgrades, as they may assist other projects.

Comments

[Bharath Muppa]

I made that list for my project. It was really painfully to migrate it completely.

You can do it in phases:

1. Just migrate to higher version and check is everything working how it was, as Migrating to mdc is not mandatory, you can rollback your changes and still use non mdc version for now.

2. MDC migration: keys areas you need to look at is ng:deep and global mat classes.

[zuhairkareem]

mat-form-field-infix should be converted to mat-mdc-form-field-infix , because I couldn't find mat-mdc-form-text-infix in the new forms

[zuhairkareem]

I was comparing it to the markup in the migrated forms in our website, not any docs as such, I made a mistake in the comment before, the class I couldn't find was mat-mdc-form-text-infix not mat-mdc-text-field-wrapper, I have updated my comment.

I had to compare the migrated material forms with pages before migration in our other environment, and add padding etc to fix a lot of issues, check TODOs one by one, because we do custom styling on material forms.

If you start doing it, you will figure out the changed classes but it is a lot of work