@ngdoc content @name Migration to Angular Material @description

<style> table { margin: 24px 2px; box-shadow: 0 1px 2px rgba(10, 16, 20, 0.24), 0 0 2px rgba(10, 16, 20, 0.12); border-radius: 2px; background-color: white; color: rgba(0,0,0,0.87); border-spacing: 0; } table thead > { vertical-align: middle; border-color: inherit; } table thead > tr { vertical-align: inherit; border-color: inherit; } table thead > tr > th { background-color: white; border-bottom: 1px solid rgba(0, 0, 0, 0.12); color: #333; font-size: 12px; font-weight: 500; padding: 8px 24px; text-align: left; line-height: 31px; min-width: 64px; } table tbody > tr > th, table tbody > tr > td { border-bottom: 1px solid rgba(0, 0, 0, 0.12); padding: 16px; text-align: left; line-height: 15px; vertical-align: top; } h1>a, h2>a, h3>a, h4>a { font-weight: 500; } </style>

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

• AngularJS Material features that have moved to the Angular CDK
• Changes to the theming system
• The extraction of the AngularJS Material layout system into a separate library
• Alternative, light-weight layout options available in the Angular CDK
• Typography
• A comparison of AngularJS Material to Angular Material features
• New components in Angular Material

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.

<a name="cdk"></a> 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

<a name="theming"></a> 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:

<hljs lang="scss"> // 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); } </hljs> <hljs lang="html"> <!-- You can use normal Angular class bindings to toggle the alternate styles. --> <div [class.alternate-button]="isAlternateMode"> <button mat-button>Save changes</button> </div> </hljs>

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.

<a name="layout"></a> 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:

• MDN Flexbox and Grid documentation
• A Visual Guide to CSS3 Flexbox Properties
• Flexbox Zombies
• Flexbox Froggy
• Grid by Example
• A Complete Guide to Grid
• Learn CSS Grid

<a name="flex-layout"></a> Flex Layout

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

The package contains the following:

• A Declarative API that includes attributes like fxLayout, fxFlex, fxHide, fxShow, and more.
• A Responsive API that includes attributes like fxLayout.lt-md, fxFlex.gt-sm, fxHide.gt-xs, [ngClass.sm], [ngStyle.xs], and more.
• Both APIs include CSS Grid features in addition to the CSS Flexbox features from AngularJS Material.
• The ability to define Custom Breakpoints
• A MediaObserver service that allows subscribing to MediaQuery activation changes

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

• When using Flexbox only: up to ~46 KB
• When using Flexbox and Grid: up to ~60 KB
  • Core: ~23 KB, Flex: ~17 KB, Grid: ~14 KB, Extended: ~6 KB

<a name="cdk-layout"></a> 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:

• A MediaMatcher service that provides access to the low level, native MediaQueryList
• A set of Breakpoints that match the Material Design responsive layout grid breakpoints
• A BreakpointObserver service that offers APIs for responding to changes in viewport size based on predefined breakpoints.

<a name="typography"></a> Typography

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

Angular Material also adds the following typography features:

• Customization via Sass mixins that are similar to the theme configuration mixins
• Utility Sass mixins and functions for use in styling your custom components

<a name="comparison"></a> 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.

<a name="new-components"></a> 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.