Angular Material Upgrade Planner
Pick a source and target Angular Material version (8–22) for an ordered upgrade plan — MDC migration, legacy removal, Material 3 theming, and ng update commands.
Choose your upgrade path
Angular Material 20 → Angular Material 21
(5 steps)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 21 requires the same toolchain as Angular 21: Node 20.19+/22.12+/24 and TypeScript 5.9.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@21 @angular/cli@21 @angular/material@21
Material 21 adds utility classes to apply Material Design system tokens directly in templates, as an alternative to referencing the --mat-sys-* CSS variables in your styles.
Angular Aria ships in developer preview with headless, accessible component patterns (combobox, listbox, and more) you can compose alongside Material components.
Angular Material 21 → Angular Material 22
(5 steps)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.
Material 22 matches Angular 22: TypeScript 6.0 is required (5.9 and below unsupported) and Node 20 support is dropped (Node 22 minimum, also 24/26). Upgrade your toolchain first.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@22 @angular/cli@22 @angular/material@22
Angular 22 makes ChangeDetectionStrategy.OnPush the default. This affects your app’s components (Material’s own components are already OnPush) — audit any component that relied on automatic check-always behavior.
Signal Forms are production-ready and integrate with Angular Material and Angular Aria, and Angular Aria reaches stable. Consider adopting Signal Forms for Material form controls.
Tip: Always upgrade Angular Material together with Angular core (their majors must match) and one major at a time. The hardest hops are the MDC rewrite at v15 and the Material 3 theming switch at v18 — budget extra time for visual QA there. This is a representative checklist; confirm specifics against the official Angular Material guides for your versions.
Upgrading Angular Material 20 to Angular Material 22
This plan covers the full path from Angular Material 20 to Angular Material 22 — 2 version hops and 10 steps in total. Upgrade Angular Material together with Angular core, one major at a time, running ng update for each hop so the Material migration schematics apply. Commit and run thorough visual QA between hops.
Hops in this path
- Angular Material 20 → Angular Material 21 — 5 steps
- Angular Material 21 → Angular Material 22 — 5 steps
Before you start
- Upgrade on a branch and keep Angular Material's major in lockstep with Angular core.
- Get on the latest minor/patch of Angular Material 20 before the first hop.
- Plan extra time for visual QA on the MDC (v15) and Material 3 theming (v18) hops if they fall in this range.