material-components-android Documentation

File: README.md Copy Chapter

[MAINTENANCE MODE] Material Components for Android

At Google I/O 2026, Material Android announced that we're "all-in" on Compose,
alongside the official
Android Compose-first announcement,
marking a new chapter in Android development.

This means that the Views-based Material Components for Android library
(MDC-Android) is now in maintenance mode.

There are no more planned feature releases for Views, so all projects using the
Views library should begin or continue
migrating to Compose
to get the latest Material Design and Android platform updates.

For more information, see the following resources:

• Android Compose-first Blog Post
• Android Compose-first Doc
• Material Android is Compose-first Blog Post
• Compose Material 3 Getting Started Guide
• Compose Material 3 Releases Page
• Compose Material 3 API Reference Docs
• Jetpack Compose Homepage
• Migrate XML Views to Jetpack Compose Guide

Getting Started Copy Chapter

For information on how to get started with Material Components for Android,
take a look at our Getting Started guide.

Submitting Bugs or Feature Requests Copy Chapter

For usage questions: ask on
Stack Overflow.

Bugs or feature requests should be submitted at our GitHub Issues section.

Note: If your issue or feature request is for Material Jetpack Compose, please
file it at the Compose Issue Tracker
instead.

Useful Links Copy Chapter

• All Components
• Getting Started
• Contributing
• Using Snapshot Version
• Building From Source
• Catalog App
• Class
  documentation
  (external site)
• MDC-Android on Stack
  Overflow
  (external site)
• Android Developer’s
  Guide
  (external site)
• Material.io (external site)
• Material Design Guidelines (external site)

Documentation Copy Chapter

• Directory structure
• Components

File: docs/getting-started.md Copy Chapter

[MAINTENANCE MODE] Material Components for Android

At Google I/O 2026, Material Android announced that we're "all-in" on Compose,
alongside the official
Android Compose-first announcement,
marking a new chapter in Android development.

This means that the Views-based Material Components for Android library
(MDC-Android) is now in maintenance mode.

There are no more planned feature releases for Views, so all projects using the
Views library should begin or continue
migrating to Compose
to get the latest Material Design and Android platform updates.

For more information, see the following resources:

• Android Compose-first Blog Post
• Android Compose-first Doc
• Material Android is Compose-first Blog Post
• Compose Material 3 Getting Started Guide
• Compose Material 3 Releases Page
• Compose Material 3 API Reference Docs
• Jetpack Compose Homepage
• Migrate XML Views to Jetpack Compose Guide

Legacy Views Getting Started Steps Copy Chapter

1. Migration guidance Copy Section

Take a look at our guide and
codelab to help you migrate your codebase
using Material Components for Android to the new Material 3 system.

Additionally, if you are still using the legacy Design Support Library, take a
look at our
legacy guide to
help you migrate your codebase to Material Components for Android.

2. Maven library dependency Copy Section

Material Components for Android is available through Google's Maven Repository.
To use it:

1. Open the build.gradle file for your application.

2. Make sure that the repositories section includes Google's Maven Repository
   google(). For example:

   groovy Copy

   allprojects {
       repositories {
         google()
         mavenCentral()
       }
     }

3. Add the library to the dependencies section:

   groovy Copy

   dependencies {
       // ...
       implementation 'com.google.android.material:material:<version>'
       // ...
     }

Visit
Google's Maven Repository
or
MVN Repository
to find the latest version of the library.

Note: In order to use the new Material3 themes and component styles, you
should depend on version 1.5.0 or later.

Note: In order to use the new Material3Expressive themes and component
styles, you should depend on version 1.14.0 or later.

New Namespace and AndroidX

If your app currently depends on the original Design Support Library, you can
make use of the
Refactor to AndroidX…
option provided by Android Studio. Doing so will update your app's dependencies
and code to use the newly packaged androidx and com.google.android.material
libraries.

If you don't want to switch over to the new androidx and
com.google.android.material packages yet, you can use Material Components via
the com.android.support:design:28.0.0 dependency.

Note: You should not use the com.android.support and
com.google.android.material dependencies in your app at the same time.

Non-Transitive R Classes (referencing library resources programmatically)

Starting with version 1.13.0-alpha12, the Material library is built with AGP
8.7.3 (or later) and android.nonTransitiveRClass=true, meaning
R classes are no longer transitive
and resources must be fully qualified with their library path when used
programmatically.

For example, since colorPrimary is defined in the AppCompat library, you must
refer to it as androidx.appcompat.R.attr.colorPrimary as opposed to
com.google.android.material.R.attr.colorPrimary or R.attr.colorPrimary.

For a Material defined resource like colorOnPrimary, you must refer to it as
com.google.android.material.R.attr.colorOnPrimary.

To opt out of this new behavior, set android.nonTransitiveRClass=false in your
gradle.properties file. Then you can access any resource without a fully
qualified path (i.e., simply R.<resource-type>.<resource-name>).

Note: This is relevant for all types of library resources, not just
attribute references.

3. Android SDK compilation Copy Section

In order to use the latest versions of Material Components for Android and the
AndroidX Jetpack libraries, you will have to install the latest version of
Android Studio and update your app to meet the following requirements:

• compileSdkVersion -> 35 or later (see the
  Android 15 app migration guide)
• minSdkVersion -> 21 or later

4. Java 8 compilation Copy Section

The latest Material and AndroidX Jetpack libraries now require your app to be
compiled with Java 8. See the
Java 8 language features and APIs documentation
for more information on Java 8 support and how to enable it for your app.

5. Gradle, AGP, and Android Studio Copy Section

When using MDC-Android version 1.13.0 and above, you will need to make sure
your project is built with the following minimum requirements, in order to
support the latest build features such as XML macro:

• Gradle version 8.9
• Android Gradle Plugin (AGP) version 8.7.3
• Android Studio Ladybug, version 2024.2.1

6. `AppCompatActivity` Copy Section

Use AppCompatActivity to ensure that all the components work correctly. If you
are unable to extend from AppCompatActivity, update your activities to use
AppCompatDelegate.
This will enable the AppCompat or Material versions of components to be inflated
(depending on your theme), among other important things.

7. `Material3` theme inheritance Copy Section

We recommend you perform an app-wide migration by changing your app theme to
inherit from a Material3 theme. Be sure to test thoroughly afterwards, since
this may change the appearance and behavior of existing layout components.

Check out the new Material Theme Builder which can be used to generate your
Material3 app theme, with all of the Material Color System roles filled out
based on your brand colors.

• Web
• Figma

Note: If you can't change your theme, you can continue to inherit from
an AppCompat or MaterialComponents theme and add some new theme attributes
to your theme. See the
AppCompat or MaterialComponents themes
section for more details.

**`Material3Expressive` themes**

Note: You must depend on library version 1.14.0-alpha01 or later to use
Theme.Material3Expressive.* themes, which are required for
Widget.Material3Expressive.* component styles.

Here are the Material3Expressive themes you can use to get the latest
component styles and theme-level attributes, as well as their Material3
equivalents when applicable.

**`Material3` themes**

Here are the Material3 themes you can use to get the latest component styles
and theme-level attributes, as well as their MaterialComponents equivalents
when applicable.

Update your app theme to inherit from one of these themes:

<style name="Theme.MyApp" parent="Theme.Material3.DayNight.NoActionBar">
    
</style>

For more information on how to set up theme-level attributes for your app, take
a look at our Theming guide, as well as our
Dark Theme guide for why it's important to inherit from the
DayNight theme.

Material3 themes enable a custom view inflater, which replaces default
components with their Material counterparts. Currently, this replaces the
following XML components:

• `

@color/my_app_primary
@color/my_app_primary_dark
@color/my_app_secondary
@color/my_app_background
@color/my_app_error

@color/my_app_primary_variant
@color/my_app_secondary_variant
@color/my_app_surface
@color/my_app_on_primary
@color/my_app_on_secondary
@color/my_app_on_background
@color/my_app_on_error
@color/my_app_on_surface
@color/mtrl_scrim
@style/TextAppearance.MaterialComponents.Headline1
@style/TextAppearance.MaterialComponents.Headline2
@style/TextAppearance.MaterialComponents.Headline3
@style/TextAppearance.MaterialComponents.Headline4
@style/TextAppearance.MaterialComponents.Headline5
@style/TextAppearance.MaterialComponents.Headline6
@style/TextAppearance.MaterialComponents.Subtitle1
@style/TextAppearance.MaterialComponents.Subtitle2
@style/TextAppearance.MaterialComponents.Body1
@style/TextAppearance.MaterialComponents.Body2
@style/TextAppearance.MaterialComponents.Caption
@style/TextAppearance.MaterialComponents.Button
@style/TextAppearance.MaterialComponents.Overline

@color/my_app_primary_inverse
@color/my_app_primary_container
@color/my_app_on_primary_container
@color/my_app_secondary_container
@color/my_app_on_secondary_container
@color/my_app_tertiary
@color/my_app_on_tertiary
@color/my_app_tertiary_container
@color/my_app_on_tertiary_container
@color/my_app_surface_variant
@color/my_app_on_surface_variant
@color/my_app_inverse_surface
@color/my_app_inverse_on_surface
@color/my_app_outline
@color/my_app_error_container
@color/my_app_on_error_container
@style/TextAppearance.Material3.DisplayLarge
@style/TextAppearance.Material3.DisplayMedium
@style/TextAppearance.Material3.DisplaySmall
@style/TextAppearance.Material3.HeadlineLarge
@style/TextAppearance.Material3.HeadlineMedium
@style/TextAppearance.Material3.HeadlineSmall
@style/TextAppearance.Material3.TitleLarge
@style/TextAppearance.Material3.TitleMedium
@style/TextAppearance.Material3.TitleSmall
@style/TextAppearance.Material3.BodyLarge
@style/TextAppearance.Material3.BodyMedium
@style/TextAppearance.Material3.BodySmall
@style/TextAppearance.Material3.LabelLarge
@style/TextAppearance.Material3.LabelMedium
@style/TextAppearance.Material3.LabelSmall
@style/ShapeAppearance.Material3.SmallComponent
@style/ShapeAppearance.Material3.MediumComponent
@style/ShapeAppearance.Material3.LargeComponent

### 8. Add Material components

Take a look at our
[documentation](https://material.io/components?platform=android) for the full
list of available Material components. Each component's page has specific
instructions on how to implement it in your app.

Let's use [text fields](components/TextField.md) as an example.

#### **Implementing a text field via XML**

The default
[outlined text field](https://material.io/go/design-text-fields#outlined-text-field)
XML is defined as:

```xml
<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/textfield_label">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>
</com.google.android.material.textfield.TextInputLayout>

Note: If you are not using a theme that inherits from a Material3
theme, you will have to specify the text field style as well, via
style="@style/Widget.Material3.TextInputLayout.OutlinedBox"

Other text field styles are also provided. For example, if you want a
filled text field
in your layout, you can apply the Material3 filled style to the text field
in XML:

<com.google.android.material.textfield.TextInputLayout
    style="@style/Widget.Material3.TextInputLayout.FilledBox"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="@string/textfield_label">

  <com.google.android.material.textfield.TextInputEditText
      android:layout_width="match_parent"
      android:layout_height="wrap_content"/>
</com.google.android.material.textfield.TextInputLayout>

Contributors Copy Chapter

Material Components for Android welcomes contributions from the community. Check
out our contributing guidelines as well as an overview of the
directory structure before getting started.

Useful Links Copy Chapter

• Theming Guide
• Contributing
• Using Snapshot Version
• Building From Source
• Catalog App
• Class documentation
• MDC-Android on Stack Overflow
• Android Developer’s Guide
• Material.io
• Material Design Guidelines