# 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](https://material.io/go/design-buttons) - [Class definition](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java) - [Class overview](https://developer.android.com/reference/com/google/android/material/button/MaterialButton) ## 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: ```xml ``` 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. ```xml ``` ## 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. ```xml ``` ### Filled, unelevated button The `UnelevatedButton` style represents an unelevated button with a colored background. ```xml ``` ### 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. ```xml ``` ### 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. ```xml ``` ### 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: ```xml ``` The following shows a text button with an icon: ```xml ``` 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: ```xml ``` ## 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](FloatingActionButton.md) instead.