material-components_material-components-android/docs/getting-started.md

Getting started with Material Components for Android

1. Depend on our library

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 a maven section with the "https://maven.google.com" endpoint. For example:

  allprojects {
    repositories {
      jcenter()
      maven {
        url "https://maven.google.com"
      }
    }
  }

3. Add the library to the dependencies section:

  dependencies {
    // ...
    compile 'com.google.android.material:material:[Library version code]'
    // ...
  }

Note: 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.

2. Change your app theme to inherit from a Material Components theme

Doing an app-wide migration by changing your app theme to inherit from a Material Components theme is the recommended approach. However, be sure to test thoroughly afterwards, as components in existing layouts may change their looks and behavior.

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

Material Components themes

The following is the list of Material Components themes you can use to get the latest component styles and theme-level attributes.

• Theme.MaterialComponents
• Theme.MaterialComponents.NoActionBar
• Theme.MaterialComponents.Light
• Theme.MaterialComponents.Light.NoActionBar
• Theme.MaterialComponents.Light.DarkActionBar

Update your app theme to inherit from one of these themes, e.g.:

<style name="MyAppTheme" parent="Theme.MaterialComponents">
    <!-- ... -->
</style>

For more information on how to set up theme-level color attributes for your app, take a look at our Color Theming guide.

AppCompat Themes

You can also incrementally test new Material components without changing your app theme. This allows you to keep your existing layouts looking and behaving the same, while introducing new components to your layout one at a time.

However, you must add the following new theme attributes to your existing app theme, or you will encounter ThemeEnforcement errors:

<style name="MyAppTheme" parent="Theme.AppCompat">

  <!-- Original AppCompat attributes. -->
  <item name="colorPrimary">@color/my_app_primary_color</item>
  <item name="colorPrimaryDark">@color/my_app_primary_dark_color</item>
  <item name="colorAccent">@color/my_app_accent_color</item>

  <!-- New MaterialComponents attributes. -->
  <item name="colorPrimaryLight">?attr/colorPrimary</item>
  <item name="colorSecondary">?attr/colorPrimary</item>
  <item name="colorSecondaryLight">?attr/colorPrimaryLight</item>
  <item name="colorSecondaryDark">?attr/colorPrimaryDark</item>
  <item name="scrimBackground">@color/mtrl_scrim_color</item>
  <item name="snackbarButtonStyle">?attr/borderlessButtonStyle</item>

</style>

3. Add a Material component to your app

Take a look at our documentation 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 as an example.

Implementing a text field via XML

The default filled text field XML is defined as:

<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 Material Components theme, you will have to specify the text field style as well, via style="@style/Widget.MaterialComponents.TextInputLayout.FilledBox"

Other text field styles are also provided. For example, if you want an outlined text field in your layout, you can apply the Material Components outlined style to the text field in XML:

<com.google.android.material.textfield.TextInputLayout
    style="@style/Widget.MaterialComponents.TextInputLayout.OutlineBox"
    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

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

• Contributing
• Building From Source
• Class documentation
• MDC-Android on Stack Overflow
• Android Developer’s Guide
• Material.io
• Material Design Guidelines