Migration to Angular Material and the Angular CDK

While AngularJS Material has not yet entered Long Term Support (LTS) mode like AngularJS has, the Angular Components team's resources are focused on Angular Material and the Angular Component Dev Kit (CDK).

For applications with long-term development and support plans, consideration should be made for migration to the latest version of Angular, Angular Material, and the CDK.

The official ngUpgrade guide covers general practices around AngularJS to Angular migration. This document provides additional guidance specific to AngularJS Material (v1.1.9+).

Table of Contents

Key Concepts

The ngUpgrade Preparation Guide covers a number of important steps for preparing your application for the migration. In addition to this preparation work, you should use the content of this document in order to make migration plans based on how features and components have changed between AngularJS Material and Angular Material.

Angular CDK

Some of the features of AngularJS Material have been made more generic and moved into the Angular CDK.

These include:

AngularJS Material CDK
$mdPanel Overlay
md-virtual-repeat *cdkVirtualFor
md-virtual-repeat-container cdk-virtual-scroll-viewport
$mdLiveAnnouncer LiveAnnouncer
$mdUtil's bidi() function Directionality service and Dir directive
md-input's md-no-autogrow and max-rows CdkTextareaAutosize
layout system Covered in separate section of this guide

Theming

AngularJS Material performs most theming at run-time. While this allows developers to configure themes dynamically in JavaScript, it also incurs substantial performance cost to generate CSS during application load.

Angular Material performs theming at compile-time with Sass. While this approach requires more up-front set-up, it completely removes all JavaScript execution cost associated with theming. The use of Sass also moves the theming system to a more well-supported and broadly-understood toolchain.

Defining palettes

AngularJS Material supports defining custom palettes or extending existing palettes.

In Angular Material, custom palette creation, including definition of hues and contrast colors, can be accomplished by copying one of the provided palettes, modifying it, and then using it in your custom theme creation.

Defining themes

AngularJS Material uses a provider, $mdThemingProvider, to define the theme configuration used to generate styles during application loading. This provider also includes a default theme for cases when no custom palettes are provided.

Angular Material has no default theme; a theme CSS file must always be included. You can either use one of the pre-built theme files, or define a custom theme with Sass mixins, including the output in your application just like any other CSS asset.

Defining themes at run-time

AngularJS Material uses a service, $mdTheming, to define themes and generate CSS styles at run-time.

Defining and generating theme CSS at run-time is not supported by Angular Material. However, loading additional theme CSS into your application (or modifying an existing theme's link node to swap theme CSS files) at run-time is supported.

Your application can choose to generate additional themes at compile-time or build an API to dynamically generate theme CSS on-demand. In either case, it is possible to lazy load the theme CSS at run-time.

Applying themes to your application

AngularJS Material has a custom directive, md-theme, to apply a theme to a specific component and its children.

Rather than providing a special directive API, Angular Material's Sass-based theming system relies on standard Sass mixins and vanilla CSS selectors. For example, you can customize an individual button (or set of buttons) by defining a class and applying it to a parent element:

// Create a CSS class to use an alternate button theme, $alternate-theme, which you have // already defined. .alternate-button { @include mat-button-theme($alternate-theme); }

Just like any other CSS, these classes can be applied to any element in your application and can be added/removed/toggled to swap colors at run-time.

See the full documentation for details on themes, including examples of multiple themes.

Dynamically applying themes

AngularJS Material's md-theme and md-theme-watch directives support data binding like md-theme="{{ dynamicTheme }}" md-theme-watch.

With Angular Material, you can make use of Angular's ngClass API to dynamically apply classes associated with specific theming configurations like [ngClass]="dynamicThemeClass". You can also use normal Angular class bindings to toggle classes like [class.my-dark-theme]="isDarkMode".

Applying theming to custom components

AngularJS Material's md-colors directive and $mdColors service support looking up and dynamically applying theme-palette-hue-opacity color combinations as CSS properties to your application's custom components.

Angular Material uses the mat-color Sass function to lookup theme colors and Sass mixins with CSS selectors (see alternate-button example of a class above) to style application or library components.

Accessing Hues

AngularJS Material's Hue classes (md-hue-1, md-hue-2, md-hue-3) are used to modify a component's hues.

These classes are not supported out of the box with Angular Material, but you can use the mat-color Sass function to lookup the desired Hues and assign them to all of the appropriate CSS selectors and CSS properties, for a specific component, in a theme mixin.

Browser header and system status bar coloring on mobile

AngularJS Material's theme system supports modifying the browser header and system status bar colors.

Angular's Meta service can be used to dynamically modify <meta> tags that affect browser header and status bar colors. The AngularJS Material docs for this feature have links to learn more about the specific <meta> tags.

Note about CSS variables

Once the team begins phasing out support for IE11, the theming system will be revisited with CSS Variables (also known as CSS Custom Properties) in mind.

Changes to Layout Features

The AngularJS Material layout system includes includes attributes and classes like layout, flex, show, hide, etc.

Since AngularJS Material's inception, browser support for CSS Flexbox has broadly improved and CSS Grid has become widely available. Application developers should carefully consider the the costs of additional JavaScript run-time dependencies versus native alternatives when choosing an approach to layout.

Many of the AngularJS Material layout APIs map to straightforward, vanilla CSS using Flexbox and media queries. We recommend checking out the following documentation and tutorials:

Flex Layout

This comprehensive layout system was moved into its own project (beta).

The package contains the following:

This library adds a nontrivial payload cost as reported by source-map-explorer in v7.0.0-beta.24

Angular CDK Layout

The CDK's layout capabilities offer a lightweight alternative (or complement) to larger, full-blown layout systems. This capability adds 3.06 KB as reported by source-map-explorer with Angular CDK v7.3.7.

The CDK's Layout capability offers:

Typography

AngularJS Material typography classes align with the Angular Material typography classes.

Angular Material also adds the following typography features:

Comparison of Features and Migration Tips

Angular Material introduces a number of new components and features that do not exist in AngularJS Material. Angular Material also makes greater use of semantic HTML and native elements to improve accessibility.

Directives

Most components use the same name between the two libraries, changing the md- prefix to mat-. For example, <md-card> becomes <mat-card>. Some element directives changed to attribute directives, for instance <md-subheader> changed to matSubheader.

Component and Directive comparison reference

Directive Old (md-) New (mat-) Special Notes
autocomplete Docs Docs
autofocus Docs Docs cdkFocusInitial
button Docs Docs
calendar Docs - The datepicker has a mat-calendar component, but it cannot be used in stand-alone mode.
card Docs Docs
checkbox Docs Docs
chip Docs Docs
chip-remove Docs Docs matChipRemove
chips Docs Docs
colors Docs - mat-color mixin supports static theme color lookups.
contact-chips Docs - Not implemented
content Docs Docs cdkScrollable
datepicker Docs Docs
divider Docs Docs
fab-speed-dial Docs - Not implemented
fab-toolbar Docs - Not implemented
grid-list Docs Docs
highlight-text Docs - Not implemented
icon Docs Docs
ink-ripple Docs Docs matRipple
input Docs Docs matInput
input-container Docs Docs mat-form-field
list Docs Docs
menu Docs Docs
menu-bar Docs - Not implemented
nav-bar Docs Docs mat-tab-nav-bar
nav-item Docs Docs mat-tab-link
optgroup Docs Docs
option Docs Docs
progress-linear Docs Docs mat-progress-bar
progress-circular Docs Docs mat-progress-spinner
radio-button Docs Docs
radio-group Docs Docs
select Docs Docs
select-on-focus Docs - Not implemented
sidenav Docs Docs
sidenav-focus Docs - autofocus only supports focusing the first focusable element.
switch Docs Docs mat-slide-toggle
slider Docs Docs
slider-container Docs - See Migration Notes below
subheader Docs Docs matSubheader
swipe Docs - See HammerJS setup and Hammer.Swipe
tabs Docs Docs
textarea Docs Docs
toolbar Docs Docs
tooltip Docs Docs
truncate Docs - Not implemented
virtual-repeat Docs Docs cdk-virtual-scroll-viewport and *cdkVirtualFor
whiteframe Docs Guide Based on classes and mixins

Component and Directive Migration Notes

  1. md-slider-container helped style and position a span and input along with the md-slider. You can add elements or components next to your mat-slider, then position and style them as desired.

Service comparison reference

Service Old New Special Notes
$mdAriaProvider Docs - See Migration Notes below
$mdBottomSheet Docs Docs MatBottomSheet
$mdColors Docs - mat-color mixin supports static theme color lookups.
$mdCompiler Docs - See Migration Notes below
$mdCompilerProvider Docs - See Migration Notes below
$mdDateLocaleProvider Docs Docs MomentDateAdapter
$mdDialog Docs Docs MatDialog
$mdGestureProvider Docs - See Migration Notes below
$mdIcon Docs Docs svgIcon
$mdIconProvider Docs Docs MatIconRegistry
$mdInkRipple Docs Docs
$mdInkRippleProvider Docs Docs MAT_RIPPLE_GLOBAL_OPTIONS
$mdInteraction Docs - Not implemented
$mdLiveAnnouncer Docs Docs CDK LiveAnnouncer
$mdMedia Docs Docs CDK BreakpointObserver.isMatched() or Flex Layout's MediaObserver service
$mdPanel Docs Docs CDK Overlay
$mdPanelProvider Docs - Not implemented
$mdProgressCircularProvider Docs - Not implemented
$mdSidenav Docs - See Migration Notes below
$mdSticky Docs - See Migration Notes below
$mdTheming Docs - Sass mixins support custom component theming.
$mdThemingProvider Docs - Sass mixins support static, custom theme creation. Use Angular's Meta service for browser coloring features.
$mdToast Docs Docs MatSnackBar

Service Migration Notes

  1. This article covers Chrome DevTools' Lighthouse Accessibility Auditing Tool. It provides guidance and two additional options for accessibility testing. Also note that the documentation for every Angular Material component includes a section with accessibility recommendations.
  2. $mdCompiler and the related $mdCompilerProvider are AngularJS-specific solutions. Similar tools and APIs are not needed when working with Angular.
  3. Angular Material uses HammerJS. To disable gesture detection, do not import HammerJS in your project. Angular Material does not do click hijacking, so the APIs related to that feature aren't needed.
  4. $mdSidenav is a convenience to allow calling $mdSidenav('right').toggle() or $mdSidenav('left').close() from components, without the need to have an actual reference to each md-sidenav instance. If you need functionality like this with Angular Material, you can use Angular's @ViewChild Decorator to get a reference to the MatDrawer or MatSidenav instance. Then you can store that reference in a service for use from multiple components.
  5. $mdSticky uses the browser's native position: sticky when supported and only supplies a workaround for browsers like IE11 that do not support native sticky positioning. For Angular Material, you should use the native position: sticky and provide your own solution for IE11.

New Components

These are new components found in Angular Material and the Angular CDK that do not exist in AngularJS Material.

The mat- and cdk- prefixes have been omitted to make this table more readable.

Directive New Special Notes
badge Docs
button-toggle Docs
drag-drop Docs CDK
expansion-panel Docs
paginator Docs
sort-header Docs
stepper Docs Unstyled CDK and Material versions available.
table Docs Unstyled CDK and Material versions available.
tree Docs Unstyled CDK and Material versions available.