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 8 → Angular Material 9
(4 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 9 requires the same toolchain as Angular 9: Node 10.13+ and TypeScript 3.6–3.8.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@9 @angular/cli@9 @angular/material@9
Material moves onto Ivy with Angular 9 and introduces component test harnesses (@angular/cdk/testing) for more robust component tests. Mostly dependency and minor API changes this hop.
Angular Material 9 → Angular Material 10
(4 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 10 requires the same toolchain as Angular 10: Node 12+ and TypeScript 3.9.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@10 @angular/cli@10 @angular/material@10
Material 10 adds the mat-date-range-input / mat-date-range-picker and refreshes several styles. Material tracks Angular core; review any deprecation warnings the update prints.
Angular Material 10 → Angular Material 11
(4 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 11 requires the same toolchain as Angular 11: TypeScript 4.0.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@11 @angular/cli@11 @angular/material@11
Mostly dependency bumps and small fixes for Material this hop. Run the update schematics and review the changelog for any component you customize heavily.
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 8 to Angular Material 11
This plan covers the full path from Angular Material 8 to Angular Material 11 — 3 version hops and 12 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 8 → Angular Material 9 — 4 steps
- Angular Material 9 → Angular Material 10 — 4 steps
- Angular Material 10 → Angular Material 11 — 4 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 8 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.