Apr 16, 2020

Migrating to Material Components for Android

From Design Support Library 👉 MDC 1.0.0 👉 MDC 1.1.0 and beyond

Posted by


We recently announced Material Design Components (MDC) 1.0.0 — a library update that brings Material Theming, new widgets, dark theme support and other exciting features to your Android app.

MDC replaces the Design Support Library. This guide will show you how to migrate your codebase so you can make use of the new attributes, styles, and widgets. If you’re on MDC 1.0.0 this also provides the necessary migration steps to 1.1.0. Be sure to check out our corresponding video guide as well!

link
Copy link Link copied

A simplified theming example

This guide uses a simplified app to demonstrate the migration process. It uses an AppCompat theme, widgets from the Design Support Library (including a button with a custom background), and various other elements that require migration. We’ll start with an app theme which uses the traditional AppCompat template:

Example app using AppCompat and the Design Support Library

link
Copy link Link copied

Migrating from the Support Library to Jetpack

Before you can use MDC, you need to migrate from the Support Library to Android Jetpack. Jetpack uses the new androidx.* namespace and splits the previous Support Library packages into separately maintained, semantically versioned libraries, providing feature parity as well as new libraries. MDC is built with AndroidX libraries so migration is mandatory.

To migrate to AndroidX, we recommend following the official developer documentation or watching the “Migrating to AndroidX: The time is right” talk from Android Dev Summit ’19. The ‘Refactor > Migrate to AndroidX’ tool in Android Studio will refactor your Design Support Library dependency to MDC.

Note: Jetpack and MDC artifacts with version 1.0.0 are binary compatible with the Support Library 28.0.0 artifacts. If you’re not on version 28 then we recommend upgrading to this first and then migrating.

link
Copy link Link copied

Updating to MDC 1.0.0

If you used the Android Studio ‘Refactor > Migrate to AndroidX’ tool during Jetpack migration, your Design Support Library dependency should have mapped to MDC 1.0.0 and you can skip this section.

If not, you will need to manually update your dependency:

You will also need to change the package namespace of any usages of the Design Support Library classes (in XML layouts and in code) from android.support.design.* to com.google.android.material.*. To do so, take a look at the class mapping table.

link
Copy link Link copied

Changing your theme(s)

You need to ensure that your app theme inherits from a Material Components theme. The same applies to any additional themes and theme overlays you may have in your project.

If you were previously using an AppCompat theme variant, the MDC-Android theme variants map one-to-one with these. In most cases, simply swap out the AppCompat portion of the parent with MaterialComponents.

See the full theme and theme overlay mapping tables below:

AppCompat theme MDC-Android theme
Theme.AppCompat Theme.MaterialComponents
Theme.AppCompat.NoActionBar Theme.MaterialComponents.NoActionBar
Theme.AppCompat.Dialog.* Theme.MaterialComponents.Dialog.*
Theme.AppCompat.DialogWhenLarge Theme.MaterialComponents.DialogWhenLarge
Theme.AppCompat.Light Theme.MaterialComponents.Light
Theme.AppCompat.Light.DarkActionBar Theme.MaterialComponents.Light.DarkActionBar
Theme.AppCompat.Light.NoActionBar Theme.MaterialComponents.Light.NoActionBar
Theme.AppCompat.Light.Dialog.* Theme.MaterialComponents.Light.Dialog.*
Theme.AppCompat.Light.DialogWhenLarge Theme.MaterialComponents.Light.DialogWhenLarge
Theme.AppCompat.DayNight Theme.MaterialComponents.DayNight
Theme.AppCompat.DayNight.DarkActionBar Theme.MaterialComponents.DayNight.DarkActionBar
Theme.AppCompat.DayNight.NoActionBar Theme.MaterialComponents.DayNight.NoActionBar
Theme.AppCompat.DayNight.Dialog.* Theme.MaterialComponents.DayNight.Dialog.*
Theme.AppCompat.DayNight.DialogWhenLarge Theme.MaterialComponents.DayNight.DialogWhenLarge

AppCompat theme overlay MDC-Android theme overlay
ThemeOverlay.AppCompat ThemeOverlay.MaterialComponents
ThemeOverlay.AppCompat.Light ThemeOverlay.MaterialComponents.Light
ThemeOverlay.AppCompat.Dark ThemeOverlay.MaterialComponents.Dark
ThemeOverlay.AppCompat.*.ActionBar ThemeOverlay.MaterialComponents.*.ActionBar.*
ThemeOverlay.AppCompat.Dialog.* ThemeOverlay.MaterialComponents.Dialog.*
N/A ThemeOverlay.MaterialComponents.*.BottomSheetDialog
N/A ThemeOverlay.MaterialComponents.MaterialAlertDialog.*
N/A ThemeOverlay.MaterialComponents.MaterialCalendar.*
N/A ThemeOverlay.MaterialComponents.Toolbar.*

link
Copy link Link copied

Example updates

Example app using MDC 1.0.0 and Theme.MaterialComponents.* theme
link
Copy link Link copied

Button changes

Having changed our dependency to MDC 1.0.0 and our app theme to inherit from Theme.MaterialComponents.*, we can observe some unexpected changes to buttons in our example app. We have lost our custom background! They now mostly make use of the green accent color and have wider letter spacing in their text labels.

Buttons in MDC 1.0.0

To understand why this has happened, we need to start by taking a look at how we’ve added these buttons in our layout (as framework <Button>s):

So, what’s going on? 🤔

link
Copy link Link copied

MDC widgets and auto-inflation

Like AppCompat, MDC will replace some framework widgets with MDC equivalents at inflation time. This makes it possible to ship new features and bugfixes without having to swap all your declarations for a new type. This is done via MaterialComponentsViewInflater, an extension of AppCompatViewInflater.

See the full widget auto-inflation mapping table below:

Note: In MDC 1.0.0 only Buttons were replaced. The other widgets above were added in subsequent versions of the library.

Our example app was previously replacing the framework <Button>s with <AppCompatButton>s because we had a Theme.AppCompat.* theme. Having migrated to a Theme.MaterialComponents.* theme, this has changed to <MaterialButton>s which has an updated default style.

Unlike AppCompatButtonMaterialButton did not support custom backgrounds until release 1.2.0-alpha06 of MDC-Android. This is covered in more detail, along with a workaround, in the “Shape” section below.

We will keep this as is for now.

link
Copy link Link copied

Updating to MDC 1.1.0

lot has changed in MDC between 1.0.0 and 1.1.0! The new features include:

We’re now ready to bump our MDC dependency version to 1.1.0:

Note: Some AndroidX dependencies, such as AppCompat, may also need updating at this time. While not strictly required, we recommend updating to the latest stable versions if possible.

link
Copy link Link copied

Some expected changes and common issues

MDC 1.1.0 changes some default widget styling to better comply with the Material Design guidelines. After upgrading you may, however, notice some unexpected changes to certain widget colors and other attributes.

Example app using MDC 1.1.0

In our example above, buttons have changed once again, the colors of text and icons have changed, FABs are now a shade of teal, and the text field looks entirely different. Oh dear! Don’t worry, your theme is likely missing some of the important MDC attributes while also having some AppCompat or framework attributes you no longer need. Let’s understand these issues by going through some common migration scenarios.

link
Copy link Link copied

Text field changes

The default style for text fields has changed in MDC to a new, improved version backed by user research.

Text fields in MDC 1.1.0+

We recommend sticking with this version for improved usability and configurability. However, we realize that this may not immediately fit with your brand and design system.

To revert back to the legacy text field, adjust the style in your layout to use the Design Support Library version:

Alternatively, you can make this the default style for all text fields in your theme(s):

Legacy Design Support Library text field

link
Copy link Link copied

Prefer MDC styles and widgets

As we’ve seen above, widgets previously in the Design Support Library have since become part of MDC. In most cases there are new Widget.MaterialComponents.* styles that replace Widget.Design.* styles, along with new attributes that enable additional features. While opting out is possible, we recommend adopting the new MDC styles.

For components that were not part of the Design Support Library, in some cases there is now a Material version of the class. We saw this above with AppCompatButton and MaterialButton. We recommend using MDC classes over AppCompat or framework equivalents, if available. These widgets use updated Material Design design guidelines by default and support the full set of MDC attributes, which enable Material Theming and other features.

There are a few scenarios you should consider:

  • Widgets used directly in layouts should change to MDC versions (see the “MDC widgets and auto-inflation” section above to see which widgets can be kept as framework tags)
  • Any styles, default styles and default style attributes should change to MDC versions
  • Any widgets used programmatically or as parents for custom classes should change to MDC versions

See the full widget and style mapping tables below:

MDC-Android widget (moved from Design Support Library) Design Support Library default style MDC-Android default style Default style attr
AppBarLayout Widget.Design.AppBarLayout Widget.MaterialComponents.AppBarLayout.* appBarLayoutStyle
BottomNavigationView Widget.Design.BottomNavigationView Widget.MaterialComponents.BottomNavigationView bottomNavigationStyle
BottomSheetBehavior Widget.Design.BottomSheet.Modal Widget.MaterialComponents.BottomSheet.* bottomSheetStyle
BottomSheetDialog
BottomSheetDialogFragment
Theme.Design.Light.BottomSheetDialog Theme.MaterialComponents.*.BottomSheetDialog
ThemeOverlay.MaterialComponents.*.BottomSheetDialog
bottomSheetDialogTheme
CollapsingToolbarLayout Widget.Design.CollapsingToolbar N/A N/A
FloatingActionButton Widget.Design.FloatingActionButton Widget.MaterialComponents.FloatingActionButton floatingActionButtonStyle
NavigationView Widget.Design.NavigationView Widget.MaterialComponents.NavigationView navigationViewStyle
Snackbar Widget.Design.Snackbar Widget.MaterialComponents.Snackbar snackbarStyle
TabLayout
TabItem
Widget.Design.TabLayout Widget.MaterialComponents.TabLayout tabStyle
TextInputLayout
TextInputEditText
Widget.Design.TextInputLayout Widget.MaterialComponents.TextInputLayout.* textInputStyle

AppCompat widget AppCompat default style AppCompat default style attr MDC-Android widget MDC-Android default style MDC-Android default style attr
AlertDialog.Builder AlertDialog.AppCompat
ThemeOverlay.AppCompat.Dialog.Alert
alertDialogStyle
alertDialogTheme
MaterialAlertDialogBuilder MaterialAlertDialog.MaterialComponents
ThemeOverlay.MaterialComponents.MaterialAlertDialog
alertDialogStyle
materialAlertDialogTheme
AppCompatAutoCompleteTextView Widget.AppCompat.AutoCompleteTextView autoCompleteTextViewStyle MaterialAutoCompleteTextView Widget.MaterialComponents.AutoCompleteTextView.*
ThemeOverlay.MaterialComponents.AutoCompleteTextView.*
autoCompleteTextViewStyle
AppCompatButton Widget.AppCompat.Button buttonStyle MaterialButton Widget.MaterialComponents.Button materialButtonStyle
AppCompatCheckBox Widget.AppCompat.CompoundButton.CheckBox checkboxStyle MaterialCheckbox Widget.MaterialComponents.CompoundButton.CheckBox checkboxStyle
AppCompatImageView N/A N/A ShapeableImageView Widget.MaterialComponents.ShapeableImageView N/A
AppCompatRadioButton Widget.AppCompat.CompoundButton.RadioButton radioButtonStyle MaterialRadioButton Widget.MaterialComponents.CompoundButton.RadioButton radioButtonStyle
AppCompatTextView Widget.AppCompat.TextView N/A MaterialTextView Widget.MaterialComponents.TextView N/A
CardView CardView cardViewStyle MaterialCardView Widget.MaterialComponents.CardView materialCardViewStyle
PopupMenu Widget.AppCompat.PopupMenu.* popupMenuStyle N/A Widget.MaterialComponents.PopupMenu.* popupMenuStyle
SwitchCompat Widget.AppCompat.CompoundButton.Switch switchStyle SwitchMaterial Widget.MaterialComponents.CompoundButton.Switch switchStyle
Toolbar Widget.AppCompat.Toolbar toolbarStyle MaterialToolbar Widget.MaterialComponents.Toolbar toolbarStyle

Be sure to also check out the full list of Android components for widgets new to MDC as well as usage documentation.

link
Copy link Link copied

Example updates

Replaces widgets with MDC versions

In our example, we need to change some of the widgets in our layout to use MDC versions:

link
Copy link Link copied

Color

New attributes

The MDC color palette draws directly from the Material Design color system.

As a result of the shared history between MDC-Android, AppCompat and the framework, the resulting set of color attributes comprises the following:

  • Existing attributes from the framework that are appropriately named (eg. android:colorBackground)
  • Existing attributes from AppCompat that are appropriately named (eg. colorPrimary and colorError)
  • New attributes introduced by MDC (eg. colorSurface, colorOnPrimary, etc.)
MDC color attributes with baseline light theme values
MDC color attributes with baseline dark theme values

These attributes are used by MDC widgets to tint their backgrounds, text, icons and more. Knowing which widgets use which colors requires inspecting the default widget styles in the source code.

There are also colors from AppCompat and the framework that still exist but no longer apply to this new system. The Theme.MaterialComponents.* themes do their best to backport these old attributes for widgets that still rely on them, eg.

However, you should consider these attributes deprecated; either use a more appropriate MDC attribute or phase them out.

See the full color attribute mapping table below:

AppCompat / framework color attr MDC-Android color attr
colorPrimary colorPrimary
colorPrimaryDark colorPrimaryVariant
(specify android:statusBarColor explicitly)
N/A colorOnPrimary
colorAccent colorSecondary
N/A colorSecondaryVariant
N/A colorOnSecondary
N/A colorSurface
N/A colorOnSurface
android:colorBackground android:colorBackground
N/A colorOnBackground
colorError colorError
N/A colorOnError
android:textColorPrimary, android:textColorSecondary, etc. N/A
(prefer MDC "on" attrs or use defaults)
colorControlNormal, colorControlHighlight, colorControlActivated N/A
(prefer MDC "on" attrs or use defaults)
Note: These are still used to tint MaterialCheckBox, MaterialRadioButton, SwitchMaterial and MaterialToolbar icons.

link
Copy link Link copied

Example updates

Update to new color attributes

In our example, we need to update our app theme to override the preferred color attributes:

Note: We have not overridden all of the color attributes and are relying on the defaults for colorSurfacecolorError, etc, which is perfectly acceptable. We have also not specified a dark theme palette.

Use “on” color attributes where appropriate

We should also switch from using an @color to one of the new “on” color attributes for our contained button text color:

Example app with updated MDC color attributes (fixed FAB color)

link
Copy link Link copied

Typography

New TextAppearance styles/attributes

The MDC type scales draw directly from the Material Design type system.

A new set of TextAppearance.MaterialComponents.* styles and corresponding textAppearance* theme attributes have been introduced, which replace existing AppCompat / framework styles.

MDC type attributes

These attributes are used by MDC widgets to style text. Knowing which widgets use which type scales requires inspecting the default widget styles in the source code.

See the full type style and attribute mapping table below:

AppCompat text style MDC-Android text style MDC-Android text attr
TextAppearance.AppCompat.Display4 TextAppearance.MaterialComponents.Headline1 textAppearanceHeadline1
TextAppearance.AppCompat.Display3 TextAppearance.MaterialComponents.Headline2 textAppearanceHeadline2
TextAppearance.AppCompat.Display2 TextAppearance.MaterialComponents.Headline3 textAppearanceHeadline3
TextAppearance.AppCompat.Display1 TextAppearance.MaterialComponents.Headline4 textAppearanceHeadline4
TextAppearance.AppCompat.Headline TextAppearance.MaterialComponents.Headline5 textAppearanceHeadline5
TextAppearance.AppCompat.Title
TextAppearance.AppCompat.Large
TextAppearance.MaterialComponents.Headline6 textAppearanceHeadline6
TextAppearance.AppCompat.Subhead
TextAppearance.AppCompat.Menu
TextAppearance.MaterialComponents.Subtitle1 textAppearanceSubtitle1
TextAppearance.AppCompat.Small TextAppearance.MaterialComponents.Subtitle2 textAppearanceSubtitle2
TextAppearance.AppCompat.Body1 TextAppearance.MaterialComponents.Body1 textAppearanceBody1
TextAppearance.AppCompat.Body2 TextAppearance.MaterialComponents.Body2 textAppearanceBody2
TextAppearance.AppCompat.Button TextAppearance.MaterialComponents.Button textAppearanceButton
TextAppearance.AppCompat.Caption TextAppearance.MaterialComponents.Caption textAppearanceCaption
N/A TextAppearance.MaterialComponents.Overline textAppearanceOverline

link
Copy link Link copied

Example updates

Update to new type attributes

In our example, we need to update the TextViews within the card in the layout to use the preferred type attributes:

Customize type scales with font family

We can also optionally override type scales in our app theme to use a custom font family, with XML or downloadable fonts via Android Studio:

Note: For this example, we have only overridden some of the type scales. If you’re using a custom font, we recommend overriding all of the type scales for brand consistency.

Example app with updated MDC type attributes (updated font family)

link
Copy link Link copied

Shape

ShapeAppearance styles/attributes

The Material Design shape system is a way to apply treatments to the corners of MDC widgets, split into small, medium and large component categories.

This takes the form of Android ShapeAppearance.* styles with corresponding theme attributes. They include a cornerFamily — rounded or cut — and cornerSize* as a dimension.

MDC shape attributes

These attributes are used by MDC widgets to style their backgrounds. Knowing which widgets apply to which shape categories requires inspecting the default widget styles in the source code.

link
Copy link Link copied

Widget backgrounds

The class that implements this functionality is MaterialShapeDrawable. All MDC widgets use this drawable as their background by default and you can also consider using it for custom views. It handles shape theming, backported shadow rendering, dark theme elevation overlays and more.

As a result, we advise against using android:background with custom XML drawables on MDC widgets as this will override the MaterialShapeDrawable. You may notice that the default styles for most MDC widgets specify

to specifically avoid this. Rather, prefer using shapeAppearanceshapeAppearanceOverlay and backgroundTint attributes to adjust background shape and color.

However, there are exceptions:

link
Copy link Link copied

Example updates

Remove background attrs that do not work with shape theming

In our example, we can remove some widget attributes that are now handled by shape theming:

Customize shape with corner family and size

We can also optionally override shape styles in our app theme to express our brand:

Example app with updated MDC shape attributes (updated corner radii)

Restore button custom gradient background

Finally, here’s how to restore our button’s custom gradient background by explicitly using AppCompatButton (along with the new MDC button type theming attribute):

If you’re using MDC-Android 1.2.0-alpha-06 (or later) then you can rely on MaterialButton respecting android:background. Keep in mind that you may need to clear the backgroundTint (which is set to colorPrimary in the Widget.MaterialComponents.Button default style):

Button with restored custom gradient background

link
Copy link Link copied

What’s next?

We’ve successfully gone through the process of migrating from the Design Support Library, to MDC 1.0.0 and finally to MDC 1.1.0. We’ve migrated our usages of AppCompat and have made use of Material Theming.

We encourage you to try out new widgets and features in MDC that were not part of the Design Support Library.

The next feature release of MDC 1.2.0— is well underway with multiple alpha releases out at the time of writing. Exciting new updates include Slider and ShapeableImageView components along with the first Android release of the Material motion system!

As always, we encourage you to file bug reports and feature requests on GitHub. Also be sure to check out our Android companion example apps and Build a Material Theme.

We highly encourage migrating to MDC 1.1.0 (or later). If you’ve successfully migrated or if you’re having trouble doing so, reach out to us on Twitter @MaterialDesign and @AndroidDev.