Skip to main content
This guide documents breaking changes introduced in major versions of Angular Material and CDK to help you upgrade your applications.
Always review breaking changes before upgrading to a new major version.

​
Version 21.0.0 (November 2025)

Version 21.0.0 introduces several breaking changes to improve API consistency and remove deprecated code.

​
CDK Breaking Changes

Several internal factory functions have been removed:
  • LIVE_ANNOUNCER_ELEMENT_TOKEN_FACTORY
  • TREE_KEY_MANAGER_FACTORY
  • TREE_KEY_MANAGER_FACTORY_PROVIDER
These were internal APIs that should not have been used directly. No migration needed for most users.
SCSS variable names have been updated:
// ❌ Removed
$z-index-overlay-container
$z-index-overlay
$dark-backdrop-background
$z-index-overlay-backdrop

// ✅ Use instead
$overlay-container-z-index
$overlay-z-index
$overlay-backdrop-color
$overlay-backdrop-z-index
Portal directives have been renamed:
// ❌ Removed
import { TemplatePortalDirective, PortalHostDirective } from '@angular/cdk/portal';

// ✅ Use instead
import { CdkPortal, CdkPortalOutlet } from '@angular/cdk/portal';
Update your templates:
<!-- ❌ Old -->
<ng-template portalHost></ng-template>
<ng-template portal></ng-template>

<!-- ✅ New -->
<ng-template cdkPortalOutlet></ng-template>
<ng-template cdkPortal></ng-template>
Custom TestElement implementations must now provide setContenteditableValue method:
class CustomTestElement implements TestElement {
  // New required method
  async setContenteditableValue(value: string): Promise<void> {
    // Implementation
  }
}

​
Material Breaking Changes

Many component factory functions have been removed:Autocomplete:
  • MAT_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY
  • MAT_AUTOCOMPLETE_SCROLL_STRATEGY_FACTORY
  • MAT_AUTOCOMPLETE_SCROLL_STRATEGY_FACTORY_PROVIDER
Button:
  • MAT_BUTTON_TOGGLE_GROUP_DEFAULT_OPTIONS_FACTORY
  • MAT_FAB_DEFAULT_OPTIONS_FACTORY
Checkbox:
  • MAT_CHECKBOX_DEFAULT_OPTIONS_FACTORY
Datepicker:
  • MAT_DATEPICKER_SCROLL_STRATEGY_FACTORY
  • MAT_DATEPICKER_SCROLL_STRATEGY_FACTORY_PROVIDER
  • MAT_DATE_LOCAL_FACTORY
These were internal implementation details. Most applications won’t need changes.
Animation constants have been removed:
// ❌ Removed
import { matBottomSheetAnimations } from '@angular/material/bottom-sheet';
import { matDialogAnimations } from '@angular/material/dialog';
import { matDatepickerAnimations } from '@angular/material/datepicker';
import { matExpansionAnimations } from '@angular/material/expansion';
import { matFormFieldAnimations } from '@angular/material/form-field';
import { matMenuAnimations } from '@angular/material/menu';
import { matSelectAnimations } from '@angular/material/select';
import { matSnackBarAnimations } from '@angular/material/snack-bar';
import { matStepperAnimations } from '@angular/material/stepper';
import { matTabsAnimations } from '@angular/material/tabs';
import { matTooltipAnimations } from '@angular/material/tooltip';
If you were customizing animations, you’ll need to use CSS/SCSS instead.
MatCommonModule has been removed along with related types:
// ❌ Removed
import { MatCommonModule, SanityChecks, MATERIAL_SANITY_CHECKS } from '@angular/material/core';

// ✅ No replacement needed
// Import specific component modules directly
import { MatButtonModule } from '@angular/material/button';
Several core utilities have been removed:
// ❌ Removed
import { AnimationCurves, AnimationDurations } from '@angular/material/core';

// ✅ Use CSS variables or define your own
:root {
  --animation-duration: 200ms;
  --animation-curve: cubic-bezier(0.4, 0.0, 0.2, 1);
}
Also removed:
  • NativeDateAdapter.useUtcForDisplay

​
Material Date Adapters

Factory functions removed from date adapters:
// ❌ Removed
import { MAT_MOMENT_DATE_ADAPTER_OPTIONS_FACTORY } from '@angular/material-moment-adapter';
import { MAT_LUXON_DATE_ADAPTER_OPTIONS_FACTORY } from '@angular/material-luxon-adapter';

// ✅ Provide options directly
providers: [
  {
    provide: MAT_DATE_LOCALE,
    useValue: 'en-US'
  },
  {
    provide: MAT_MOMENT_DATE_ADAPTER_OPTIONS,
    useValue: { useUtc: true }
  }
]

​
Version 20.0.0

Version 20 focused on Angular 20 compatibility with minimal breaking changes.

​
Key Changes

  • Updated peer dependencies to Angular 20
  • Improved standalone component support
  • Enhanced TypeScript 5.x support

​
Version 19.0.0

​
Material Design 3

Version 19 introduced Material Design 3 (M3) theming: 
@use '@angular/material' as mat;

$theme: mat.define-theme((
  color: (
    theme-type: light,
    primary: mat.$violet-palette,
  ),
));

html {
  @include mat.all-component-themes($theme);
}

​
Migration Strategies

1

Review the changelog

Always read the full CHANGELOG before upgrading.
2

Update incrementally

Update one major version at a time. Don’t skip versions.
# Update to v20 first
ng update @angular/material@20

# Then update to v21
ng update @angular/material@21
3

Run ng update

Angular’s update command handles many migrations automatically:
ng update @angular/material@latest
4

Test thoroughly

Run your full test suite after updating:
ng test
ng e2e
ng build --configuration production
5

Update custom themes

If you have custom themes, test them in both light and dark modes.

​
Common Migration Issues

Problem: Import errors after upgradeSolution: Update import paths
// Old path
import { CdkPortal } from '@angular/cdk/portal/portal-directives';

// New path
import { CdkPortal } from '@angular/cdk/portal';
Problem: Theme mixin errorsSolution: Update to new M3 API or use M2 compatibility mode
// Use M2 compatibility
@include mat.m2-all-component-themes($theme);

// Or migrate to M3
@include mat.all-component-themes($theme);
Problem: Cannot import animation constantsSolution: Remove animation imports and use CSS/SCSS for customization
.mat-mdc-dialog-container {
  animation-duration: 300ms !important;
}
Problem: DI errors for factory functionsSolution: These were internal - usually no action needed. If you were using them, provide dependencies directly.

​
Deprecation Policy

APIs are deprecated for at least 2 major versions before removal.
  1. Deprecation Announced - API marked with @deprecated JSDoc
  2. Console Warnings - Runtime warnings in development mode
  3. Two Versions - API remains functional for 2+ versions
  4. Removal - API removed in a major version

​
Getting Help

Migration Guides

Detailed migration guides for major versions

GitHub Issues

Report problems or ask questions

Stack Overflow

Community support and answers

Angular Blog

Release announcements and guides

​
Stay Updated

Follow @angular on Twitter
Subscribe to the Angular blog
Watch the components repository
Join the Angular Discord

Build docs developers (and LLMs) love

Get started for freeTalk to us