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