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 16 → Angular Material 17
(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 17 requires the same toolchain as Angular 17: Node 18.13+/20.9+ and TypeScript 5.2–5.4.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@17 @angular/cli@17 @angular/material@17
The @angular/material/legacy-* packages are removed in Material 17. A schematic logs a fatal error and blocks the update if your app still imports legacy components — you must finish migrating to the MDC components first. (As a stopgap you can keep Material 16 on Angular 17 until v18.)
Angular Material 17 → Angular Material 18
(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 18 requires the same toolchain as Angular 18: Node 18.19+/20.11+/22 and TypeScript 5.4–5.5.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@18 @angular/cli@18 @angular/material@18
Define themes with mat.define-theme(), which is based on Material 3 design tokens implemented as CSS custom properties. Configure color, typography, and density dimensions. M2 (mat.define-light-theme) is still supported, so migrate themes when ready.
$theme: mat.define-theme();
Angular Material 18 → Angular Material 19
(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 19 requires the same toolchain as Angular 19: Node 18.19+/20.11+/22 and TypeScript 5.5–5.8.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@19 @angular/cli@19 @angular/material@19
Material 19 refines the theming system: enable use-system-variables to emit system tokens, and override them with the mat.theme-overrides mixin. A simpler, token-driven theming model.
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 16 to Angular Material 19
This plan covers the full path from Angular Material 16 to Angular Material 19 — 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 16 → Angular Material 17 — 4 steps
- Angular Material 17 → Angular Material 18 — 4 steps
- Angular Material 18 → Angular Material 19 — 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 16 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.