@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>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+).
- 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
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.
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 |
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.
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.
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.
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.
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.
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".
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.
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.
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.
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.
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
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
MediaQueryactivation 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
- Core:
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
MediaMatcherservice that provides access to the low level, nativeMediaQueryList - A set of
Breakpointsthat match the Material Design responsive layout grid breakpoints - A
BreakpointObserverservice that offers APIs for responding to changes in viewport size based on predefined breakpoints.
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
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.
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.
| 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 |
md-slider-containerhelped style and position aspanandinputalong with themd-slider. You can add elements or components next to yourmat-slider, then position and style them as desired.
| 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 |
- 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.
$mdCompilerand the related$mdCompilerProviderare AngularJS-specific solutions. Similar tools and APIs are not needed when working with Angular.- 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.
$mdSidenavis a convenience to allow calling$mdSidenav('right').toggle()or$mdSidenav('left').close()from components, without the need to have an actual reference to eachmd-sidenavinstance. If you need functionality like this with Angular Material, you can use Angular's @ViewChild Decorator to get a reference to theMatDrawerorMatSidenavinstance. Then you can store that reference in a service for use from multiple components.$mdStickyuses 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 nativeposition: stickyand provide your own solution for IE11.
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. |