# Buttons [Buttons](https://m3.material.io/components/buttons/overview) allow users to take actions, and make choices, with a single tap. There are two variants of common buttons. ![2 types of common buttons](assets/buttons/commonbutton-types.png) 1. Default button 2. Toggle button ![Diagram of button styles and toggle behaviors](assets/buttons/commonbutton-styles.png) There are five button styles, in order of emphasis: 1. Elevated button 2. Filled button 3. Filled tonal button 4. Outlined button 5. Text button Buttons have default and toggle behaviors: A. Default button
B. Toggle (unselected)
C. Toggle (selected)
**Note:** Images use various dynamic color schemes. ## Design & API documentation * [Material 3 (M3) spec](https://m3.material.io/components/buttons/overview) * [API reference](https://developer.android.com/reference/com/google/android/material/button/package-summary) ## Anatomy ![Elevated button anatomy diagram](assets/buttons/commonbutton-anatomy.png) 1. Container 2. Label text 3. Icon (optional) More details on anatomy items in the [component guidelines](https://m3.material.io/components/buttons/guidelines#653b660b-e9d8-48ad-9f53-67fb3d76e09e). ## M3 Expressive ### M3 Expressive update Before you can use `Material3Expressive` component styles, follow the [`Material3Expressive` themes setup instructions](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md#material3expressive-themes). 4 button changes in the expressive update

4 button changes in the expressive update

1. Five sizes 2. Toggle (selection) 3. Two shapes 4. Two small padding widths Buttons now have a wider variety of shapes and sizes, toggle functionality, and can change shape when selected [More on M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive) **Types and naming:** * Default and toggle (selection) * Color styles are now configurations. (elevated, filled, tonal, outlined, text) **Shapes:** * Round and square options * Shape morphs when pressed * Shape morphs when selected **Sizes:** * Extra small * Small (existing, default) * Medium * Large * Extra large **New padding for small buttons:** * 16dp (recommended to match padding of new sizes) * 24dp (deprecated) ### M3 Expressive styles #### Buttons

Filled

Default

| Checked

| Unchecked

---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------- ![Default expressive filled button example in dark theme](assets/buttons/default-filled-button-dark.png) | ![Checked expressive filled button in dark theme](assets/buttons/checked-filled-button-dark.png) | ![Unchecked expressive filled button in light theme](assets/buttons/default-filled-button-dark.png) ![Default expressive filled button example in light theme](assets/buttons/default-filled-button-light.png) | ![Checked expressive filled button in light theme](assets/buttons/checked-filled-button-light.png) | ![Unchecked expressive filled button in dark theme](assets/buttons/default-filled-button-light.png) By default, the filled button is uncheckable. To make it checkable, enable the `android:checkable` attribute in style or layout. ```xml

Filled tonal

Default

| Checked

| Unchecked

------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------- ![Default expressive filled tonal button in light theme](assets/buttons/default-filled-tonal-light.png) | ![Checked expressive filled tonal button in dark theme](assets/buttons/checked-filled-tonal-dark.png) | ![Unchecked expressive filled tonal button in light theme](assets/buttons/default-filled-tonal-light.png) ![Default expressive filled tonal button in dark theme](assets/buttons/default-filled-tonal-dark.png) | ![Checked expressive filled tonal button in light theme](assets/buttons/checked-filled-tonal-light.png) | ![Unchecked expressive filled tonal button in dark theme](assets/buttons/default-filled-tonal-dark.png) By default, the tonal button is uncheckable. To make it checkable, enable the `android:checkable` attribute in style or layout. ```xml

Outlined

Default

| Checked

| Unchecked

------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------- ![Default expressive outlined button button in light theme](assets/buttons/default-outlined-button-light.png) | ![Checked expressive outlined button in dark theme](assets/buttons/checked-outlined-button-dark.png) | ![Unchecked expressive outlined button in light theme](assets/buttons/default-outlined-button-light.png) ![Default expressive outlined button button in dark theme](assets/buttons/default-outlined-button-dark.png) | ![Checked expressive outlined button in light theme](assets/buttons/checked-outlined-button-light.png) | ![Unchecked expressive outlined button in dark theme](assets/buttons/default-outlined-button-dark.png) By default, the outlined button is uncheckable. To make it checkable, enable the `android:checkable` attribute in style or layout. ```xml

Text

-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- The text button appears as only text until pressed. It does not have a solid fill or outline by default. ```xml

Elevated

Default

| Checked

| Unchecked

----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- ![Default expressive elevated button in light theme](assets/buttons/default-elevated-light.png) | ![Checked expressive elevated button in dark theme](assets/buttons/checked-elevated-dark.png) | ![Unchecked expressive elevated button in light theme](assets/buttons/default-elevated-light.png) ![Default expressive elevated button in dark theme](assets/buttons/default-elevated-dark.png) | ![Checked expressive elevated button in light theme](assets/buttons/checked-elevated-light.png) | ![Unchecked expressive elevated button in dark theme](assets/buttons/default-elevated-dark.png) By default, the elevated button is uncheckable. To make it checkable, enable the `android:checkable` attribute in style or layout. ```xml

Filled button with icons

Default

| Checked

| Unchecked

------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------- ![Default expressive filled icon button in light theme](assets/buttons/default-filled-icon-button-light.png) | ![Checked expressive filled icon button in dark theme](assets/buttons/checked-filled-icon-button-dark.png) | ![Unchecked expressive filled icon button in light theme](assets/buttons/default-filled-icon-button-light.png) ![Default expressive filled icon button in dark theme](assets/buttons/default-filled-icon-button-dark.png) | ![Checked expressive filled icon button in light theme](assets/buttons/checked-filled-icon-button-light.png) | ![Unchecked expressive filled icon button in dark theme](assets/buttons/default-filled-icon-button-dark.png) Icons visually communicate the button’s action and help draw attention. They should be placed on the leading side of the button, before the label text. ```xml

#### Shapes

Round

Default

| Checked

| Unchecked

Square

Default

| Checked

| Unchecked

#### Sizes **Note:** Images below show the label buttons in different sizes relatively. The actual sizes in px on mobile devices depends on the screen pixel density.

Extra small

```xml

Small

```xml

Medium

```xml

Large

```xml

Extra Large

```xml

## Key properties

Elevated button

#### Text label attributes Element | Attribute | Related method(s) | Default value -------------- | ------------------------ | --------------------------------- | ------------- **Text label** | `android:text` | `setText`
`getText` | `null` **Color** | `android:textColor` | `setTextColor`
`getTextColor` | `?attr/colorOnSurface` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_foreground_color_selector.xml)) **Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceLabelLarge` #### Container attributes Element | Attribute | Related method(s) | Default value ---------------- | --------------------- | ---------------------------------------------------------------------------- | ------------- **Color** | `app:backgroundTint` | `setBackgroundColor`
`setBackgroundTintList`
`getBackgroundTintList` | `?attr/colorSurfaceContainerLow` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_background_color_selector.xml)) **Stroke color** | `app:strokeColor` | `setStrokeColor`
`setStrokeColorResource`
`getStrokeColor` | `null` **Stroke width** | `app:strokeWidth` | `setStrokeWidth`
`setStrokeWidthResource`
`getStrokeWidth` | `0dp` **Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`
`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full` **Elevation** | `app:elevation` | `setElevation`
`getElevation` | `1dp` **Ripple color** | `app:rippleColor` | `setRippleColor`
`setRippleColorResource`
`getRippleColor` | `?attr/colorOnSurface` at 16% opacity (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_ripple_color_selector.xml)) #### Icon attributes Element | Attribute | Related method(s) | Default value ----------------------------------------------- | ----------------- | --------------------------------------------------------- | ------------- **Icon** | `app:icon` | `setIcon`
`setIconResource`
`getIcon` | `null` **Color** | `app:iconTint` | `setIconTint`
`setIconTintResource`
`getIconTint` | `?attr/colorOnSurface` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_foreground_color_selector.xml)) **Size** | `app:iconSize` | `setIconSize`
`getIconSize` | `wrap_content` **Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`
`getIconGravity` | `start` **Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`
`getIconPadding` | `8dp` #### Styles Element | Style ----------------- | --------------------------------------------- **Default style** | `Widget.Material3.Button.ElevatedButton` **Icon style** | `Widget.Material3.Button.ElevatedButton.Icon` Default style theme attribute: `?attr/materialButtonElevatedStyle` See the full list of [styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/styles.xml) and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/attrs.xml).

Filled button

#### Text label attributes Element | Attribute | Related method(s) | Default value -------------- | ------------------------ | --------------------------------- | ------------- **Text label** | `android:text` | `setText`
`getText` | `null` **Color** | `android:textColor` | `setTextColor`
`getTextColor` | `?attr/colorOnPrimary` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_foreground_color_selector.xml)) **Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceLabelLarge` #### Container attributes Element | Attribute | Related method(s) | Default value ---------------- | --------------------- | ---------------------------------------------------------------------------- | ------------- **Color** | `app:backgroundTint` | `setBackgroundColor`
`setBackgroundTintList`
`getBackgroundTintList` | `?attr/colorPrimary` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_background_color_selector.xml)) **Stroke color** | `app:strokeColor` | `setStrokeColor`
`setStrokeColorResource`
`getStrokeColor` | `null` **Stroke width** | `app:strokeWidth` | `setStrokeWidth`
`setStrokeWidthResource`
`getStrokeWidth` | `0dp` **Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`
`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full` **Elevation** | `app:elevation` | `setElevation`
`getElevation` | `2dp` **Ripple color** | `app:rippleColor` | `setRippleColor`
`setRippleColorResource`
`getRippleColor` | `?attr/colorOnPrimary` at 16% opacity (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_ripple_color_selector.xml)) #### Icon attributes Element | Attribute | Related method(s) | Default value ----------------------------------------------- | ----------------- | --------------------------------------------------------- | ------------- **Icon** | `app:icon` | `setIcon`
`setIconResource`
`getIcon` | `null` **Color** | `app:iconTint` | `setIconTint`
`setIconTintResource`
`getIconTint` | `?attr/colorOnPrimary` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_foreground_color_selector.xml)) **Size** | `app:iconSize` | `setIconSize`
`getIconSize` | `wrap_content` **Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`
`getIconGravity` | `start` **Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`
`getIconPadding` | `8dp` #### Styles Element | Style ------------------------- | ----------------------------------------------- **Default style** | `Widget.Material3.Button` **Icon style** | `Widget.Material3.Button.Icon` **Unelevated style** | `Widget.Material3.Button.UnelevatedButton` **Unelevated icon style** | `Widget.Material3.Button.UnelevatedButton.Icon` Default style theme attribute: `?attr/materialButtonStyle` See the full list of [styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/styles.xml) and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/attrs.xml).

Filled tonal button

#### Text label attributes Element | Attribute | Related method(s) | Default value -------------- | ------------------------ | --------------------------------- | ------------- **Text label** | `android:text` | `setText`
`getText` | `null` **Color** | `android:textColor` | `setTextColor`
`getTextColor` | `?attr/colorOnSecondaryContainer` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_foreground_color_selector.xml)) **Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceLabelLarge` #### Container attributes Element | Attribute | Related method(s) | Default value ---------------- | --------------------- | ---------------------------------------------------------------------------- | ------------- **Color** | `app:backgroundTint` | `setBackgroundColor`
`setBackgroundTintList`
`getBackgroundTintList` | `?attr/colorSecondaryContainer` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_background_color_selector.xml)) **Stroke color** | `app:strokeColor` | `setStrokeColor`
`setStrokeColorResource`
`getStrokeColor` | `null` **Stroke width** | `app:strokeWidth` | `setStrokeWidth`
`setStrokeWidthResource`
`getStrokeWidth` | `0dp` **Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`
`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full` **Elevation** | `app:elevation` | `setElevation`
`getElevation` | `2dp` **Ripple color** | `app:rippleColor` | `setRippleColor`
`setRippleColorResource`
`getRippleColor` | `?attr/colorOnSecondaryContainer` at 16% opacity (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_tonal_button_ripple_color_selector.xml)) #### Icon attributes Element | Attribute | Related method(s) | Default value ----------------------------------------------- | ----------------- | --------------------------------------------------------- | ------------- **Icon** | `app:icon` | `setIcon`
`setIconResource`
`getIcon` | `null` **Color** | `app:iconTint` | `setIconTint`
`setIconTintResource`
`getIconTint` | `?attr/colorOnSecondaryContainer` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/color/res/color/m3_button_foreground_color_selector.xml)) **Size** | `app:iconSize` | `setIconSize`
`getIconSize` | `wrap_content` **Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`
`getIconGravity` | `start` **Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`
`getIconPadding` | `8dp` #### Styles Element | Style ----------------- | ------------------------------------------ **Default style** | `Widget.Material3.Button.TonalButton` **Icon style** | `Widget.Material3.Button.TonalButton.Icon` Default style theme attribute: `?attr/materialButtonTonalStyle` See the full list of [styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/styles.xml) and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/attrs.xml).

Outlined button

#### Text label attributes Element | Attribute | Related method(s) | Default value -------------- | ------------------------ | --------------------------------- | ------------- **Text label** | `android:text` | `setText`
`getText` | `null` **Color** | `android:textColor` | `setTextColor`
`getTextColor` | `?attr/colorOnSurface` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_foreground_color_selector.xml)) **Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceLabelLarge` #### Container attributes Element | Attribute | Related method(s) | Default value ---------------- | --------------------- | ---------------------------------------------------------------------------- | ------------- **Color** | `app:backgroundTint` | `setBackgroundColor`
`setBackgroundTintList`
`getBackgroundTintList` | `@android:color/transparent` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_background_color_selector.xml)) **Stroke color** | `app:strokeColor` | `setStrokeColor`
`setStrokeColorResource`
`getStrokeColor` | `?attr/colorOnSurface` at 12% opacity (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_button_outline_color_selector.xml)) **Stroke width** | `app:strokeWidth` | `setStrokeWidth`
`setStrokeWidthResource`
`getStrokeWidth` | `1dp` **Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`
`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full` **Elevation** | `app:elevation` | `setElevation`
`getElevation` | `0dp` **Ripple color** | `app:rippleColor` | `setRippleColor`
`setRippleColorResource`
`getRippleColor` | `?attr/colorOnSurface` at 16% opacity (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_ripple_color_selector.xml)) #### Icon attributes Element | Attribute | Related method(s) | Default value ----------------------------------------------- | ----------------- | --------------------------------------------------------- | ------------- **Icon** | `app:icon` | `setIcon`
`setIconResource`
`getIcon` | `null` **Color** | `app:iconTint` | `setIconTint`
`setIconTintResource`
`getIconTint` | `?attr/colorOnSurface` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_foreground_color_selector.xml)) **Size** | `app:iconSize` | `setIconSize`
`getIconSize` | `wrap_content` **Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`
`getIconGravity` | `start` **Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`
`getIconPadding` | `8dp` #### Styles Element | Style ----------------- | --------------------------------------------- **Default style** | `Widget.Material3.Button.OutlinedButton` **Icon style** | `Widget.Material3.Button.OutlinedButton.Icon` Default style theme attribute: `?attr/materialButtonOutlinedStyle` See the full list of [styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/styles.xml) and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/attrs.xml).

Text button

#### Text label attributes Element | Attribute | Related method(s) | Default value -------------- | ------------------------ | --------------------------------- | ------------- **Text label** | `android:text` | `setText`
`getText` | `null` **Color** | `android:textColor` | `setTextColor`
`getTextColor` | `?attr/colorOnSurface` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_foreground_color_selector.xml)) **Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceLabelLarge` #### Container attributes Element | Attribute | Related method(s) | Default value ---------------- | --------------------- | ---------------------------------------------------------------------------- | ------------- **Color** | `app:backgroundTint` | `setBackgroundColor`
`setBackgroundTintList`
`getBackgroundTintList` | `@android:color/transparent` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_background_color_selector.xml)) **Stroke color** | `app:strokeColor` | `setStrokeColor`
`setStrokeColorResource`
`getStrokeColor` | `null` **Stroke width** | `app:strokeWidth` | `setStrokeWidth`
`setStrokeWidthResource`
`getStrokeWidth` | `0dp` **Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`
`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full` **Elevation** | `app:elevation` | `setElevation`
`getElevation` | `0dp` **Ripple color** | `app:rippleColor` | `setRippleColor`
`setRippleColorResource`
`getRippleColor` | `?attr/colorOnSurface` at 16% opacity (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_ripple_color_selector.xml)) #### Icon attributes Element | Attribute | Related method(s) | Default value ----------------------------------------------- | ----------------- | --------------------------------------------------------- | ------------- **Icon** | `app:icon` | `setIcon`
`setIconResource`
`getIcon` | `null` **Color** | `app:iconTint` | `setIconTint`
`setIconTintResource`
`getIconTint` | `?attr/colorOnSurface` (see all [states](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/color/m3_text_button_foreground_color_selector.xml)) **Size** | `app:iconSize` | `setIconSize`
`getIconSize` | `wrap_content` **Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`
`getIconGravity` | `start` **Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`
`getIconPadding` | `8dp` #### Styles Element | Style ---------------------- | ----------------------------------------------------- **Default style** | `Widget.Material3.Button.TextButton` **Icon style** | `Widget.Material3.Button.TextButton.Icon` **Full Width Buttons** | `Widget.Material3.Button.TextButton.Dialog.FullWidth` Default style theme attribute: `?attr/borderlessButtonStyle` See the full list of [styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/styles.xml) and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/attrs.xml).

## Variants of buttons ### Default button * Buttons communicate actions that people can take. * They are typically placed throughout the UI, in places like: * Dialogs * Modal windows * Forms * Cards * Toolbars * They can also be placed within standard button groups. ### Toggle button * Toggle buttons should be used for binary selections, such as Save or Favorite. When toggle buttons are pressed, they can change color, shape, and labels. * Toggle buttons should use an outlined icon when unselected, and a filled version of the icon when selected. If a filled version doesn’t exist, increase the weight instead. * By default, toggle buttons change from round to square when selected. ## Code implementation Before you can use Material buttons, you need to add a dependency to the Material components for Android library. For more information, go to the [Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md) page. **Note:** `