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 14 → Angular Material 15
(7 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 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
Angular Material 15 → Angular Material 16
(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 16 requires the same toolchain as Angular 16: Node 16.14+/18.10+ and TypeScript 4.9–5.1.
Update Material alongside the Angular core and CLI so the Material migration schematics for this version run.
ng update @angular/core@16 @angular/cli@16 @angular/material@16
Replace @angular/material/legacy-* imports with the new MDC components one component at a time, fixing styles as you go. Use the density and typography mixins (mat.<component>-density) to tune the MDC look. Legacy components are still available this version but go away in v17.
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();
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.
Plan Any Angular Material Upgrade Path
Angular Material tracks Angular's version numbers, so you upgrade them together one major at a time with ng update @angular/core@N @angular/cli@N @angular/material@N. This planner stitches together the steps for every hop between your current version and your target — so a Material 14 → 18 plan walks you through the MDC component rewrite at 15, the legacy-component removal at 17, and the Material 3 theming switch at 18, in order.
Supported Versions
How to Use This Planner
- Select your current and target versions. The URL updates so you can bookmark or share the exact path.
- Work hop by hop. Each numbered section is one major-version transition, with the
ng updatecommand and steps ordered pre-flight → requirements → update → breaking → deprecation → migration. - Filter by category to focus on, say, only breaking changes or only theming migrations.
- Tick off steps as you complete them and watch the progress bar.
- Export the plan as Markdown to drop into a PR description or upgrade ticket.
Frequently Asked Questions
- Does the Angular Material version have to match the Angular version?
- Yes. Angular Material's major version must equal the Angular core major version. Always update them together in the same hop: ng update @angular/core@N @angular/cli@N @angular/material@N. That is why this planner shows the same versions (8–22) as the Angular Upgrade Planner.
- What is the hardest Angular Material upgrade?
- Angular Material 14 → 15, where every component was rebuilt on Material Design Components (MDC). DOM structure and CSS class names changed, so custom component styles often break. The ng update schematic moves you to @angular/material/legacy-* imports first so the app keeps running, then you migrate component by component.
- What happened to the legacy components?
- The MDC migration in v15 introduced @angular/material/legacy-* packages as a temporary bridge to the old components. They were deprecated in v15 and deleted in v17 — a schematic blocks the v17 update if you still import them, so you must finish migrating to the MDC components first.
- When did Material 3 theming arrive?
- Angular Material 18 made Material 3 (M3) theming stable, using mat.define-theme() with design tokens implemented as CSS custom properties (color, typography, density). v19 added system-variable theming (mat.theme-overrides), and v20 introduced the concise mat.theme() mixin that emits --mat-sys-* variables.
- Is this an official, exhaustive upgrade guide?
- No. It is a curated checklist for planning a Material upgrade. For complete, code-aware migration steps, use the official Angular Update Guide and Angular Material documentation, and test on a branch with thorough visual QA.
- Can I export the checklist?
- Yes. Tick off steps as you complete them, then use Copy as Markdown or Download .md to paste the plan — with your progress — into a ticket or PR description.