Angular Material Upgrade Planner

Angular Material’s major version must match the Angular core major version. Update them together in the same hop, upgrade one major at a time on a branch, and run the app/tests after each hop. Commit a clean tree first.

Angular Material 12 requires the same toolchain as Angular 12: Node 12.14+ and TypeScript 4.2.

Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.

ng update @angular/core@12 @angular/cli@12 @angular/material@12

Material 12 adopts the Sass module system. Replace @import "~@angular/material/theming" with @use "@angular/material" as mat; and use mat.define-light-theme, mat.core, and mat.all-component-themes. The update includes a theming migration schematic.

@use '@angular/material' as mat;

Angular Material’s major version must match the Angular core major version. Update them together in the same hop, upgrade one major at a time on a branch, and run the app/tests after each hop. Commit a clean tree first.

Angular Material 13 requires the same toolchain as Angular 13: Node 12.20+/14.15+/16.10+ and TypeScript 4.4.

Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.

ng update @angular/core@13 @angular/cli@13 @angular/material@13

Material 13 tightens the public theming API (use mat.* functions rather than deep imports) and updates the Angular Package Format. Stop importing from internal paths if you were.

Angular Material’s major version must match the Angular core major version. Update them together in the same hop, upgrade one major at a time on a branch, and run the app/tests after each hop. Commit a clean tree first.

Angular Material 14 requires the same toolchain as Angular 14: Node 14.15+/16.10+ and TypeScript 4.6–4.8.

Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.

ng update @angular/core@14 @angular/cli@14 @angular/material@14

The MDC-based components are available under @angular/material-experimental in v14. Trying them now makes the mandatory v15 MDC migration far smoother. mat-selection-list items require explicit values.

Angular Material’s major version must match the Angular core major version. Update them together in the same hop, upgrade one major at a time on a branch, and run the app/tests after each hop. Commit a clean tree first.

Angular Material 15 requires the same toolchain as Angular 15: Node 14.20+/16.13+/18.10+ and TypeScript 4.8–4.9.

Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.

ng update @angular/core@15 @angular/cli@15 @angular/material@15

Material 15 refactors all components onto Material Design Components (MDC). DOM structure and CSS class names change, so custom component styles can break. This is the single biggest Material upgrade — budget time for visual QA.

floatLabel="never" is dropped (it only existed on the old form-field appearance). Use matTextPrefix/matTextSuffix for baseline-aligned text and matIconPrefix/matIconSuffix for centered icons. Expect density and typography differences.

The @angular/material/legacy-* packages are a temporary bridge — they are deprecated in v15 and deleted in v17, so plan your migration off them before then.

The update schematic rewrites imports to @angular/material/legacy-* so the app runs on v15 immediately with minimal changes. Then migrate component-by-component to the new (non-legacy) MDC components.

ng update @angular/material@15