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

Component token CSS variables that started with --mdc- now start with --mat-, and some are reordered (e.g. --mat-tonal-button-* becomes --mat-button-tonal-*). ng update rewrites references in your styles; check any hand-written overrides it cannot see.

Buttons gain a unified matButton selector with a new tonal appearance (matButton="tonal"), cards get appearance="filled", and dialogs accept a closePredicate to control when they can close.

<button matButton="tonal">Save</button>

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.js must be ^22.22.3, ^24.15.0 or ^26.0.0 (Node 20 is dropped). 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 OnPush the default and renames the old Default strategy to Eager. ng update adds ChangeDetectionStrategy.Eager to your existing components, so behavior is preserved. Material’s own components were already OnPush, so they are unaffected.

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.