material-components_material-components-android/docs/components/MaterialButton.md

Material Button

Material Button is a customizable button component with updated visual styles. This button component has several built-in styles to support different levels of emphasis, as typically any UI will contain a few different buttons to indicate different actions. These levels of emphasis include:

• raised button: A rectangular material button that lifts and displays ink reactions on press
• unelevated button: A button made of ink that displays ink reactions on press but does not lift

Note: MaterialButton is visually different from Button and AppCompatButton. One of the main differences is that AppCompatButton has a 4dp inset on the left and right sides, whereas MaterialButton does not. To add an inset to match AppCompatButton, set android:insetLeft and android:insetRight on the button to 4dp, or change the spacing on the button's parent layout.

When replacing buttons in your app with MaterialButton, you should inspect these changes for sizing and spacing differences.

Design & API Documentation

• Material Design guidelines: Buttons
• Class definition
• Class overview

Usage

The MaterialButton component provides a complete implementation of Material Design's button component. Example code of how to include the component in your layout:

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/button_label_enabled"/>

<com.google.android.material.button.MaterialButton
    android:id="@+id/disabled_material_button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:enabled="false"
    android:text="@string/button_label_disabled"/>

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_unelevated_button"
    style="@style/Widget.MaterialComponents.Button.UnelevatedButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/unelevated_button_label_enabled"/>

For filled buttons, your theme's colorPrimary provides the default background color of the component, and the text color is colorOnPrimary. For unfilled buttons, your theme's colorPrimary provides the default text color of the component, and the background color is transparent by default.

Note: Elevated MaterialButtons have a shadow which extends outside the bounds of the button. For this reason, the wrapping parent element should set android:clipToPadding="false" in cases where the button shadow could be clipped by the parent bounds.

  <GridLayout
      android:id="@+id/grid"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:layout_gravity="center"
      android:padding="16dp"
      android:clipToPadding="false"
      android:columnCount="2">

    <com.google.android.material.button.MaterialButton
        android:id="@+id/material_button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/button_label_enabled"/>

    <Space/>
  </GridLayout>

Styles

We provide several styles for the MaterialButton component.

Filled, elevated button (default)

The default style represents an elevated button with a colored background. This should be used for important, final actions that complete a flow, like 'Save' or 'Confirm'. If no style attribute is specified for a MaterialButton, this is the style that will be used.

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_button"
    style="@style/Widget.MaterialComponents.Button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/button_label_enabled"/>

Filled, unelevated button

The UnelevatedButton style represents an unelevated button with a colored background.

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_unelevated_button"
    style="@style/Widget.MaterialComponents.Button.UnelevatedButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/unelevated_button_label_enabled"/>

Outlined button

The OutlinedButton style has a transparent background with colored text, and a small stroke around the button. Outlined buttons are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app.

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_text_button"
    style="@style/Widget.MaterialComponents.Button.OutlinedButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/outlined_button_label_enabled"/>

Text button

The TextButton style has a transparent background with colored text. Text buttons are used for low-priority actions, especially when presenting multiple options.

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_text_button"
    style="@style/Widget.MaterialComponents.Button.TextButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/text_button_label_enabled"/>

Icon button

Every style for Material Button has an additional .Icon style. This style is meant to be used when the icon attribute is set for the button and the iconGravity is start. The .Icon style has a smaller start padding to achieve visual balance in the button when a start-gravity icon is present.

The following shows a filled, elevated button with an icon:

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_icon_button"
    style="@style/Widget.MaterialComponents.Button.Icon"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/icon_button_label_enabled"
    app:icon="@drawable/icon_24px"/>

The following shows a text button with an icon:

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_icon_button"
    style="@style/Widget.MaterialComponents.Button.TextButton.Icon"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/icon_button_label_enabled"
    app:icon="@drawable/icon_24px"/>

Note: The .Icon style should only be used for start-gravity icon buttons. If your icon is end-gravity, you cannot use a .Icon style and must instead manually adjust your padding such that the visual adjustment is mirrored.

Attributes

The following attributes can be changed for Material Button:

Description	Relevant attributes
Button padding	android:padding android:paddingLeft android:paddingRight android:paddingStart android:paddingEnd android:paddingTop android:paddingBottom
Button inset	android:insetLeft android:insetRight android:insetTop android:insetBottom
Background color	app:backgroundTint app:backgroundTintMode
Icon drawable	app:icon app:iconSize app:iconGravity
Padding between icon and button text	app:iconPadding
Icon color	app:iconTint app:iconTintMode
Stroke	app:strokeColor app:strokeWidth
The radius of all four corners of the button	app:cornerRadius
Ripple	app:rippleColor

The following shows an example of setting icon and iconPadding attributes on a button:

<com.google.android.material.button.MaterialButton
    android:id="@+id/material_icon_button"
    style="@style/Widget.MaterialComponents.Button.Icon"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/icon_button_label_enabled"
    app:icon="@drawable/icon_24px"
    app:iconPadding="8dp"/>

Theme Attribute Mapping

Filled button

style="@style/Widget.MaterialComponents.Button" (default)
style="@style/Widget.MaterialComponents.Button.Icon"
style="@style/Widget.MaterialComponents.Button.UnelevatedButton"
style="@style/Widget.MaterialComponents.Button.UnelevatedButton.Icon"

Component Attribute	Default Theme Attribute Value
android:textAppearance	textAppearanceButton
android:textColor	colorOnPrimary
iconTint	colorOnPrimary
rippleColor	colorOnPrimary at 32% opacity (pressed)
backgroundTint	colorPrimary

Outlined button

style="@style/Widget.MaterialComponents.Button.OutlinedButton"
style="@style/Widget.MaterialComponents.Button.OutlinedButton.Icon"

Component Attribute	Default Theme Attribute Value
android:textAppearance	textAppearanceButton
android:textColor	colorPrimary
iconTint	colorPrimary
rippleColor	colorPrimary at 16% opacity (pressed)
strokeColor	colorOnSurface at 12% opacity
backgroundTint	Transparent

Text button

style="@style/Widget.MaterialComponents.Button.TextButton"
style="@style/Widget.MaterialComponents.Button.TextButton.Icon"

Component Attribute	Default Theme Attribute Value
android:textAppearance	textAppearanceButton
android:textColor	colorPrimary
iconTint	colorPrimary
rippleColor	colorPrimary at 12% opacity (pressed)
backgroundTint	Transparent

Related Concepts

If your app requires actions to be persistent and readily available, you can use FloatingActionButton instead.