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 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’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.

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

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’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’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’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.

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 20 requires the same toolchain as Angular 20: Node 20.19+/22.12+/24 and TypeScript 5.8.

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

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

The mat.theme() mixin takes a map of color/typography/density and emits --mat-sys-* system CSS variables (e.g. --mat-sys-primary using light-dark()). This is the modern, concise way to theme — adopt it for new themes and dark mode.

@include mat.theme((color: ..., typography: Roboto, density: 0));

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’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.