DEV/material-components_material-components-android
1
0
Fork 0
mirror of https://github.com/material-components/material-components-android.git synced 2026-02-04 13:53:16 +08:00
Code Issues Packages Projects Releases Wiki Activity
material-components_materia.../docs/components/Button.md
pekingme 981877d06d [ButtonGroup] Added overflow feature. 
PiperOrigin-RevId: 762686060
2025-05-27 18:47:43 +00:00

1480 lines
65 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!--docs:
title: "Buttons"
layout: detail
section: components
excerpt: "A customizable button component with updated visual styles."
iconId: materialbutton
path: /catalog/buttons/
-->
# Buttons
[Buttons](https://material.io/components/buttons/) allow users to take actions,
and make choices, with a single tap.
!["Overview"](assets/buttons/buttons_hero.png)
**Contents**
* [Design and API Documentation](#design-and-api-documentation)
* [Using buttons](#using-buttons)
* [Elevated button](#elevated-button)
* [Filled button](#filled-button)
* [Filled tonal button](#filled-tonal-button)
* [Outlined button](#outlined-button)
* [Text button](#text-button)
* [Button groups](#button-groups)
* [Toggle button group](#toggle-button-groups)
* [Icon button](#icon-button)
* [Optical centering](#optical-centering)
* [Theming](#theming-buttons)
## Design and API Documentation
* [Google Material3 Spec](https://material.io/components/buttons/overview)
* [API Reference](https://developer.android.com/reference/com/google/android/material/button/package-summary)
## Using buttons
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:** `<Button>` is auto-inflated as
`<com.google.android.material.button.MaterialButton>` via
`MaterialComponentsViewInflater` when using a `Theme.Material3.*` theme.
### Making buttons accessible
Buttons support content labeling for accessibility and are readable by most
screen readers, such as TalkBack. Text rendered in buttons is automatically
provided to accessibility services. Additional content labels are usually
unnecessary.
For more information on content labels, go to the
[Android accessibility help guide](https://support.google.com/accessibility/android/answer/7158690).
### Types
There are five types of common buttons: 1\. [Elevated button](#elevated-button),
2\. [Filled button](#filled-button), 3\.
[Filled tonal button](#filled-tonal-button), 4\.
[Outlined button](#outlined-button), 5\. [Text button](#text-button).
[Toggle button](#toggle-button) is an additional pattern using a segmented
container or icon.
!["Button types - elevated, filled, filled tonal, outlined and text."](assets/buttons/buttons_types.png)
## Elevated button
[Elevated buttons](https://material.io/components/buttons/#elevated-button) are
essentially outlined buttons with a shadow. To prevent shadow creep, only use
them when absolutely necessary, such as when the button requires visual
separation from a patterned background.
### Elevated button examples
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows an elevated button with a text label.
!["Elevated button with purple text 'Elevated button' over a white background."](assets/buttons/elevated-button.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.ElevatedButton"
android:id="@+id/elevatedButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Elevated button"
/>
```
In code:
```kt
elevatedButton.setOnClickListener {
// Respond to button press
}
```
#### Adding an icon to an elevated button
The following example shows an elevated button with an icon.
!["Elevated button with purple text 'Elevated button', grey border and '+' icon
over a white background."](assets/buttons/elevated-button-icon.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.ElevatedButton.Icon"
...
app:icon="@drawable/ic_add_24dp"
/>
```
### Anatomy and key properties
An elevated button has a text label, a stroked container and an optional icon.
![Elevated button anatomy diagram](assets/buttons/elevated_button_anatomy.png)
1. Container
2. Label text
3. Icon
#### Text label attributes
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | --------------------------------- | -------------
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
**Color** | `android:textColor` | `setTextColor`<br/>`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`<br/>`setBackgroundTintList`<br/>`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`<br/>`setStrokeColorResource`<br/>`getStrokeColor` | `null`
**Stroke width** | `app:strokeWidth` | `setStrokeWidth`<br/>`setStrokeWidthResource`<br/>`getStrokeWidth` | `0dp`
**Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`<br/>`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full`
**Elevation** | `app:elevation` | `setElevation`<br/>`getElevation` | `1dp`
**Ripple color** | `app:rippleColor` | `setRippleColor`<br/>`setRippleColorResource`<br/>`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`<br/>`setIconResource`<br/>`getIcon` | `null`
**Color** | `app:iconTint` | `setIconTint`<br/>`setIconTintResource`<br/>`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`<br/>`getIconSize` | `wrap_content`
**Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`<br/>`getIconGravity` | `start`
**Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`<br/>`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
[Filled button's](https://material.io/components/buttons/#filled-button)
contrasting surface color makes it the most prominent button after the FAB. It’s
used for final or unblocking actions in a flow.
**Note** The filled button is the default style if the style is not set.
### Filled button examples
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows a filled button with a text label and a filled
container.
!["Filled button with white text 'Filled button' and purple container over a
white background."](assets/buttons/filled-button.png)
In the layout:
```xml
<Button
android:id="@+id/filledButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Filled button"
/>
```
**Note:** Since this is the default type, you don't need to specify a style tag
as long as you are using a Material Components Theme. If not, set the style to
`@style/Widget.Material3.Button`.
In code:
```kt
filledButton.setOnClickListener {
// Respond to button press
}
```
#### Adding an icon to a filled button
The following example shows a filled button with an icon.
!["Filled button with white text 'Filled button', purple container and '+' icon
over a white background."](assets/buttons/filled-button-icon.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.Icon"
...
app:icon="@drawable/ic_add_24dp"
/>
```
### Anatomy and key properties
A filled button has a text label, a filled container and an optional icon.
![Filled button anatomy diagram](assets/buttons/filled_button_anatomy.png)
1. Container
2. Label text
3. Icon
#### Text label attributes
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | --------------------------------- | -------------
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
**Color** | `android:textColor` | `setTextColor`<br/>`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`<br/>`setBackgroundTintList`<br/>`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`<br/>`setStrokeColorResource`<br/>`getStrokeColor` | `null`
**Stroke width** | `app:strokeWidth` | `setStrokeWidth`<br/>`setStrokeWidthResource`<br/>`getStrokeWidth` | `0dp`
**Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`<br/>`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full`
**Elevation** | `app:elevation` | `setElevation`<br/>`getElevation` | `2dp`
**Ripple color** | `app:rippleColor` | `setRippleColor`<br/>`setRippleColorResource`<br/>`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`<br/>`setIconResource`<br/>`getIcon` | `null`
**Color** | `app:iconTint` | `setIconTint`<br/>`setIconTintResource`<br/>`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`<br/>`getIconSize` | `wrap_content`
**Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`<br/>`getIconGravity` | `start`
**Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`<br/>`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
[Filled tonal buttons](https://material.io/components/buttons/#filled-tonal-button)
have a lighter background color and darker label color, making them less
visually prominent than a regular filled button. They’re still used for final or
unblocking actions in a flow, but may be better when these actions don’t require
quite so much emphasis.
### Filled tonal button examples
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows a filled tonal button with a text label and a filled
container.
!["Filled tonal button with white text 'Filled tonal button' and purple
container over a white background."](assets/buttons/filled-button-tonal.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.TonalButton"
android:id="@+id/filledTonalButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Filled tonal button"
/>
```
In code:
```kt
filledTonalButton.setOnClickListener {
// Respond to button press
}
```
#### Adding an icon to a filled tonal button
The following example shows a filled tonal button with an icon.
!["Filled tonal button with white text 'Filled tonal button', purple container
and '+' icon over a white
background."](assets/buttons/filled-button-tonal-icon.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.TonalButton.Icon"
...
app:icon="@drawable/ic_add_24dp"
/>
```
### Anatomy and key properties
A filled tonal button has a text label, a filled container and an optional icon.
![Filled tonal button anatomy diagram](assets/buttons/filled_button_tonal_anatomy.png)
1. Container
2. Label text
3. Icon
#### Text label attributes
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | --------------------------------- | -------------
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
**Color** | `android:textColor` | `setTextColor`<br/>`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`<br/>`setBackgroundTintList`<br/>`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`<br/>`setStrokeColorResource`<br/>`getStrokeColor` | `null`
**Stroke width** | `app:strokeWidth` | `setStrokeWidth`<br/>`setStrokeWidthResource`<br/>`getStrokeWidth` | `0dp`
**Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`<br/>`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full`
**Elevation** | `app:elevation` | `setElevation`<br/>`getElevation` | `2dp`
**Ripple color** | `app:rippleColor` | `setRippleColor`<br/>`setRippleColorResource`<br/>`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`<br/>`setIconResource`<br/>`getIcon` | `null`
**Color** | `app:iconTint` | `setIconTint`<br/>`setIconTintResource`<br/>`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`<br/>`getIconSize` | `wrap_content`
**Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`<br/>`getIconGravity` | `start`
**Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`<br/>`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
[Outlined buttons](https://material.io/components/buttons/#outlined-button) are
for actions that need attention but aren’t the primary action, such as “See all”
or “Add to cart.” This is also the button used to give someone the opportunity
to change their mind or escape a flow.
### Outlined button examples
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows an outlined button with a text label and stroked
container.
!["Outlined button with purple text 'Outlined button' and grey border over a
white background."](assets/buttons/outlined-button.png)
In the layout:
```xml
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/outlinedButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Outlined button"
/>
```
In code:
```kt
outlinedButton.setOnClickListener {
// Respond to button press
}
```
#### Adding an icon to an outlined button
The following example shows an outlined button with an icon.
!["Outlined button with purple text 'Outlined button', grey border and '+' icon
over a white background."](assets/buttons/outlined-button-icon.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.OutlinedButton.Icon"
...
app:icon="@drawable/ic_add_24dp"
/>
```
### Anatomy and key properties
An outlined button has a text label, a stroked container and an optional icon.
![Outlined button anatomy diagram](assets/buttons/outlined_button_anatomy.png)
1. Container
2. Label text
3. Icon
#### Text label attributes
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | --------------------------------- | -------------
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
**Color** | `android:textColor` | `setTextColor`<br/>`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`<br/>`setBackgroundTintList`<br/>`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`<br/>`setStrokeColorResource`<br/>`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`<br/>`setStrokeWidthResource`<br/>`getStrokeWidth` | `1dp`
**Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`<br/>`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full`
**Elevation** | `app:elevation` | `setElevation`<br/>`getElevation` | `0dp`
**Ripple color** | `app:rippleColor` | `setRippleColor`<br/>`setRippleColorResource`<br/>`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`<br/>`setIconResource`<br/>`getIcon` | `null`
**Color** | `app:iconTint` | `setIconTint`<br/>`setIconTintResource`<br/>`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`<br/>`getIconSize` | `wrap_content`
**Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`<br/>`getIconGravity` | `start`
**Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`<br/>`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 buttons](https://material.io/components/buttons/#text-button) have less
visual prominence, so should be used for low emphasis actions, such as when
presenting multiple options.
### Text button examples
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows a text button with a text label.
!["Text button with purple text 'Text button' over a white background."](assets/buttons/text-button.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.TextButton"
android:id="@+id/textButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Text button"
/>
```
In code:
```kt
textButton.setOnClickListener {
// Respond to button press
}
```
#### Adding an icon to a text button
The following example shows a text button with an icon.
!["Text button with purple text 'Text button' and '+' icon over a white
background."](assets/buttons/text-button-icon.png)
In the layout:
```xml
<Button
style="@style/Widget.Material3.Button.TextButton.Icon"
...
app:icon="@drawable/ic_add_24dp"
/>
```
### Anatomy and key properties
A text button has a text label, a transparent container and an optional icon.
![Text button anatomy diagram](assets/buttons/text_button_anatomy.png)
1. Label text
2. Icon
#### Text label attributes
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | --------------------------------- | -------------
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
**Color** | `android:textColor` | `setTextColor`<br/>`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`<br/>`setBackgroundTintList`<br/>`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`<br/>`setStrokeColorResource`<br/>`getStrokeColor` | `null`
**Stroke width** | `app:strokeWidth` | `setStrokeWidth`<br/>`setStrokeWidthResource`<br/>`getStrokeWidth` | `0dp`
**Shape** | `app:shapeAppearance` | `setShapeAppearanceModel`<br/>`getShapeAppearanceModel` | `ShapeAppearance.M3.Sys.Shape.Corner.Full`
**Elevation** | `app:elevation` | `setElevation`<br/>`getElevation` | `0dp`
**Ripple color** | `app:rippleColor` | `setRippleColor`<br/>`setRippleColorResource`<br/>`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`<br/>`setIconResource`<br/>`getIcon` | `null`
**Color** | `app:iconTint` | `setIconTint`<br/>`setIconTintResource`<br/>`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`<br/>`getIconSize` | `wrap_content`
**Gravity** (position relative to text label) | `app:iconGravity` | `setIconGravity`<br/>`getIconGravity` | `start`
**Padding** (space between icon and text label) | `app:iconPadding` | `setIconPadding`<br/>`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).
## Button groups
Button groups organize buttons and add interactions between them.
There are two types of button groups based on their shapes:
* [Button group](#button-group)
* [Connected button group](#connected-button-group)
### Button group
The default button group contains multiple related individual buttons. The
individual button's shape is preserved.
![Examples of using default button group](assets/buttons/default_button_group.png)
#### Button group examples
Source code:
* `MaterialButtonGroup`
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButtonGroup.java)
* `MaterialButton`
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows a button group with three buttons that have text
labels.
In the layout:
```xml
<com.google.android.material.button.MaterialButtonGroup
android:id="@+id/buttonGroup"
android:layout_width="wrap_content"
android:layout_height="wrap_content">
<Button
android:id="@+id/button1"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 1"
/>
<Button
android:id="@+id/button2"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 2"
/>
<Button
android:id="@+id/button3"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 3"
/>
</com.google.android.material.button.MaterialButtonGroup>
```
### Connected button group
In addition to standard button groups, connected button group also overrides the
individual button's shape to make them visually more belong to a group with 2dp
spacing, 8dp inner corners, and fully rounded outer corners.
![Examples of using connected button group](assets/buttons/connected_button_group.png)
#### Connected button group examples
Source code:
* `MaterialButtonGroup`
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButtonGroup.java)
* `MaterialButton`
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows a connected button group with three buttons that
have text labels. To correctly style a button group as connected button group,
the specific style needs to be set.
In the layout:
```xml
<com.google.android.material.button.MaterialButtonGroup
android:id="@+id/buttonGroup"
style="@style/Widget.Material3.MaterialButtonGroup.Connected"
android:layout_width="wrap_content"
android:layout_height="wrap_content">
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/button1"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 1" />
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/button2"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 2" />
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/button3"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 3" />
</com.google.android.material.button.MaterialButtonGroup>
```
### Properties
Element | Attribute | Related method(s) | Default value
------------------------------- | ------------------------ | -------------------------------------------- | -------------
**Group shape (outer corners)** | `app:shapeAppearance` | `setShapeAppearance`<br>`getShapeAppearance` | `none`
**Size of inner corners** | `app:innerCornerSize` | `setInnerCornerSize`<br>`getInnerCornerSize` | `none`
**Spacing between buttons** | `android:spacing` | `setSpacing`<br>`getSpacing` | `12dp`
**Child size change** | `app:childSizeChange` | N/A | `15%` in pressed,<br>otherwise, `0%`
**Child overflow mode** | `app:overflowMode` | `setOverflowMode`<br>`getOverflowMode` | `none`
**Overflow button icon** | `app:overflowButtonIcon` | `setOverflowButtonIcon` | `abc_ic_menu_overflow_material` (3 dots)
#### Additional attributes of child buttons
| Element | Attribute | Related | Default value |
: : : method(s) : :
| -------------- | ------------------------- | --------- | ------------------ |
| **Title of the | `app:layout_overflowText` | N/A | button's `text` |
: overflow menu : : : value, if not :
: item** : : : specified or empty :
| **Icon of the | `app:layout_overflowIcon` | N/A | `null` |
: overflow menu : : : :
: item** : : : :
#### Styles and Theme attributes
Element | Style | Theme Attribute
------------------------------ | -------------------------------------- | ---------------
**Default style** | `Widget.Material3.MaterialButtonGroup` | `?attr/materialButtonGroupStyle`
**Overflow icon button style** | `?attr/materialIconButtonStyle` | `?attr/materialButtonGroupOverflowButtonStyle`
**Overflow menu style** | `?attr/popupMenuStyle` | `?attr/materialButtonGroupOverflowPopupMenuStyle`
### Making button groups adaptive
`MaterialButtonGroup` inherits from the `LinearLayout`. It can be configured to
achieve different child arrangements for different screen sizes or foldable
screens by using `layout_width` and `layout_weight`.
#### Fixed button sizes
When child buttons should not be adjusted while screen size changes, consider
using `layout_width` on all buttons.
![Button group with fixed arrangement](assets/buttons/group_arrangement_fixed.png)
```xml
<com.google.android.material.button.MaterialButtonGroup
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:paddingBottom="8dp"
android:gravity="center_horizontal"
android:spacing="4dp">
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_button_previous_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_previous_icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_button_play_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_play_icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_button_next_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_next_icon"/>
</com.google.android.material.button.MaterialButtonGroup>
```
#### Flexible button sizes
When all child buttons are equally important or their sizes are proportional to
each other, consider using `layout_weight` on all buttons.
![Button group with flexible arrangement](assets/buttons/group_arrangement_flexible.png)
```xml
<com.google.android.material.button.MaterialButtonGroup
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:paddingBottom="8dp"
android:gravity="center_horizontal"
android:spacing="4dp">
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="0dp"
android:layout_height="wrap_content"
android:layout_weight="1"
android:contentDescription="@string/cat_button_previous_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_previous_icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="0dp"
android:layout_height="wrap_content"
android:layout_weight="2"
android:contentDescription="@string/cat_button_play_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_play_icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="0dp"
android:layout_height="wrap_content"
android:layout_weight="1"
android:contentDescription="@string/cat_button_next_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_next_icon"/>
</com.google.android.material.button.MaterialButtonGroup>
```
#### Mixed button sizes
When only some buttons are flexible for different screen sizes, consider using
`layout_weight` on these buttons but use `layout_width` on the rest as below.
![Button group with mixed arrangement](assets/buttons/group_arrangement_mixed.png)
```xml
<com.google.android.material.button.MaterialButtonGroup
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:paddingBottom="8dp"
android:gravity="center_horizontal"
android:spacing="4dp">
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_button_previous_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_previous_icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="0dp"
android:layout_height="wrap_content"
android:layout_weight="2"
android:contentDescription="@string/cat_button_play_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_play_icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_button_next_icon"
android:gravity="center"
app:iconGravity="textStart"
app:icon="@drawable/cat_button_next_icon"/>
</com.google.android.material.button.MaterialButtonGroup>
```
### Handling overflow
Overflow happens when the screen size or button group size is not enough to
display all child buttons. By default (mode `none`), the button's text will be
clipped or wrapped.
#### Overflow mode - menu
Setting `overflowMode=menu` dynamically hides child buttons that don't fit in
the current screen width in a popup menu. An icon button will be added
automatically at the end of the button group for toggling the popup menu, once
it's needed. The style of this icon button can be set via
`materialButtonGroupOverflowButtonStyle` attribute in your theme overlay. The
icon can be configured via `overflowButtonIcon` in the button group.
Every hidden child button will be represented by a `MenuItem` in the popup menu.
You can specify the menu item's title via `layout_overflowText` and the menu
item's icon via `layout_overflowIcon` in the specific button.
**Note:** Do not use the `menu` overflow mode to toggle button group, since the
toggle button group should demonstrate all available options and the current
selection.
**Note:** This feature assumes all child buttons should be visible in the group
or as a menu item in the overflow menu. Visibility of all child buttons will be
managed by the button group when setting `overflowMode=menu`.
### Split button
A specialized type of the connected button group is the split button. The
trailing button is checkable with an animated icon.
![Examples of using split button](assets/buttons/split_button.png)
#### Split button examples
Source code:
* `MaterialSplitButton`
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialSplitButton.java)
The following example shows a split button with a leading label button and a
trailing icon button that has an AnimatedVectorDrawable.
In the layout:
```xml
<com.google.android.material.button.MaterialSplitButton
android:id="@+id/splitbutton"
android:layout_width="wrap_content"
android:layout_height="wrap_content">
<Button
style="?attr/materialSplitButtonLeadingFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="@string/cat_split_button_label"
app:icon="@drawable/ic_edit_vd_theme_24dp"
/>
<Button
style="?attr/materialSplitButtonIconFilledStyle"
android:id="@+id/expand_more_or_less_filled"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_split_button_label_chevron"
app:icon="@drawable/m3_split_button_chevron_avd"
/>
</com.google.android.material.button.MaterialSplitButton>
```
The following example shows a split button with a leading icon button and a
trailing icon button that has an AnimatedVectorDrawable.
In the layout:
```xml
<com.google.android.material.button.MaterialSplitButton
android:id="@+id/splitbutton"
android:layout_width="wrap_content"
android:layout_height="wrap_content">
<Button
style="?attr/materialSplitButtonLeadingFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_split_button_label_edit"
app:icon="@drawable/ic_edit_vd_theme_24dp"
app:iconPadding="0dp"
/>
<Button
style="?attr/materialSplitButtonIconFilledStyle"
android:id="@+id/expand_more_or_less_filled_icon"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/cat_split_button_label_chevron"
app:icon="@drawable/m3_split_button_chevron_avd"
/>
</com.google.android.material.button.MaterialSplitButton>
```
### Animated Trailing Icon
The icon on the trailing button is animated. In the samples, this is done with
an AVD, `m3_split_button_chevron_avd`
[[source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/drawable/m3_split_button_chevron_avd.xml)].
### Properties
Element | Attribute | Related method(s) | Default value
--------------------------- | ---------------------- | --------------------------------------------- | -------------
**Size of inner corners** | `app:innerCornerSize` | `setInnerCornerSize`<br/>`getInnerCornerSize` | `none`
**Spacing between buttons** | `android:spacing` | `setSpacing`<br/>`getSpacing` | `2dp`
**Button size change** | `app:buttonSizeChange` | N/A | `0%`
#### Styles and Theme attributes
Element | Style | Theme Attribute
----------------------------------------- | --------------------------------------------------------- | ---------------
**Default style** | `Widget.Material3.MaterialSplitButton` | `?attr/materialSplitButtonStyle`
**Leading button primary (filled) style** | `Widget.Material3.SplitButton.LeadingButton.Filled` | `?attr/materialSplitButtonLeadingFilledStyle`
**Leading button primary (tonal) style** | `Widget.Material3.SplitButton.LeadingButton.Filled.Tonal` | `?attr/materialSplitButtonLeadingFilledTonalStyle`
**Trailing icon primary (filled) style** | `Widget.Material3.SplitButton.IconButton.Filled` | `?attr/materialSplitButtonIconFilledStyle`
**Trailing icon secondary (tonal) style** | `Widget.Material3.SplitButton.IconButton.Filled.Tonal` | `?attr/materialSplitButtonIconFilledTonalStyle`
The two new trailing icon styles `materialSplitButtonIconFilledStyle` – parented
by `materialIconButtonFilledStyle` – and
`materialSplitButtonIconFilledTonalStyle`-- parented by
`materialIconButtonFilledTonalStyle` allow for the `MaterialSplitButton` custom
behavior for `onChecked` and `onUnchecked` states.
`materialSplitButtonIconFilledStyle` is paired with default leading button
styling, with no style explicitly specified in the XML.
`materialSplitButtonIconFilledTonalStyle` is paired with
`materialButtonTonalStyle` for the leading button.
## Toggle button groups
[Toggle button group (Segmented buttons)](https://m3.material.io/components/segmented-buttons)
can be used to select from a group of choices.
There are two types of toggle buttons can be placed in a toggle button group:
* [Toggle button](#toggle-button)
* [Icon](#icon)
### Toggle button
To emphasize groups of related toggle buttons, a group should share a common
container.
#### Toggle button examples
API and source code:
* `MaterialButtonToggleGroup`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButtonToggleGroup)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButtonToggleGroup.java)
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows a toggle button with three buttons that have text
labels.
!["Toggle button example for Android with text labels - 'Button 1', 'Button 2'
and 'Button 3' - and grey/purple borders over a white
background."](assets/buttons/toggle-button-text.png)
In the layout:
```xml
<com.google.android.material.button.MaterialButtonToggleGroup
android:id="@+id/toggleButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content">
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/button1"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 1"
/>
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/button2"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 2"
/>
<Button
style="?attr/materialButtonOutlinedStyle"
android:id="@+id/button3"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:text="Button 3"
/>
</com.google.android.material.button.MaterialButtonToggleGroup>
```
In code:
```kt
toggleButton.addOnButtonCheckedListener { toggleButton, checkedId, isChecked ->
// Respond to button selection
}
```
#### Implementing an icon-only toggle button
The following example shows a toggle button with three buttons that have icons.
!["Toggle buttons with icons - heart, add and search - and grey/purple borders
over a white background."](assets/buttons/toggle-button.png)
In `res/values/styles.xml`:
```xml
<style name="Widget.App.Button.OutlinedButton.IconOnly" parent="Widget.Material3.Button.OutlinedButton">
<item name="iconPadding">0dp</item>
<item name="android:insetTop">0dp</item>
<item name="android:insetBottom">0dp</item>
<item name="android:paddingLeft">12dp</item>
<item name="android:paddingRight">12dp</item>
<item name="android:minWidth">48dp</item>
<item name="android:minHeight">48dp</item>
</style>
```
In the layout:
```xml
<com.google.android.material.button.MaterialButtonToggleGroup
...>
<Button
style="@style/Widget.App.Button.OutlinedButton.IconOnly"
...
app:icon="@drawable/ic_favorite_24dp"
/>
<Button
style="@style/Widget.App.Button.OutlinedButton.IconOnly"
...
app:icon="@drawable/ic_add_24dp"
/>
<Button
style="@style/Widget.App.Button.OutlinedButton.IconOnly"
...
app:icon="@drawable/ic_search_24dp"
/>
</com.google.android.material.button.MaterialButtonToggleGroup>
```
### Anatomy and key properties
A toggle button has a shared stroked container, icons and/or text labels.
![Toggle button anatomy](assets/buttons/toggle_button_anatomy.png)
1. Container
2. Icon
#### Selection attributes
Element | Attribute | Related method(s) | Default value
------------------------------------- | ----------------------- | ------------------------------------------------ | -------------
**Single selection** | `app:singleSelection` | `setSingleSelection`<br/>`isSingleSelection` | `false`
**Selection required** | `app:selectionRequired` | `setSelectionRequired`<br/>`isSelectionRequired` | `false`
**Enable the group and all children** | `android:enabled` | `setEnabled`<br/>`isEnabled` | `true`
#### Container attributes
Element | Attribute | Related method(s) | Default value
------------------------------- | --------------------- | --------------------------------------------- | -------------
**Size of inner corners** | `app:innerCornerSize` | `setInnerCornerSize`<br/>`getInnerCornerSize` | `0dp`
**Spacing between buttons** | `android:spacing` | `setSpacing`<br/>`getSpacing` | `0dp`
**Group shape (outer corners)** | `app:shapeAppearance` | `setShapeAppearance`</br>`getShapeAppearance` | `none`
#### Styles
Element | Style
----------------- | -----------------------------------------------------
**Default style** | `Widget.Material3.MaterialButtonToggleGroup`
Default style theme attribute: `?attr/materialButtonToggleGroupStyle`
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).
### Icon
Icons can be used as toggle buttons when they allow selection, or deselection,
of a single choice, such as marking an item as a favorite.
#### Icon example
API and source code:
* `CheckBox`
* [Class description](https://developer.android.com/reference/android/widget/CheckBox)
**Note:** The `CheckBox` API is just one of several inputs that can implement
the icon button. See other
[selection controls](https://material.io/components/selection-controls/) for
more details.
The following example shows an icon that can be used independently or in items
of a `RecyclerView`.
![Toggle icon example showing 4 images, heart icon in the upper-right corner of
each image](assets/buttons/android_toggle_button.png)
In the layout:
```xml
<CheckBox
android:id="@+id/icon"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:button="@drawable/sl_favourite_24dp"
app:buttonTint="@android:color/white"
/>
```
In `res/drawable/sl_favourite_24dp.xml`:
```xml
<selector>
<item
android:drawable="@drawable/ic_favourite_outlined_24dp"
android:state_checked="false" />
<item
android:drawable="@drawable/ic_favourite_filled_24dp"
android:state_checked="true" />
<item android:drawable="@drawable/ic_favourite_outlined_24dp" />
</selector>
```
In code:
```kt
icon.setOnCheckedChangeListener { checkBox, isChecked ->
// Respond to icon toggle
}
```
## Icon button
[Icon buttons](https://material.io/components/buttons/#icon-buttons) help users
take supplementary actions with a single tap. There are two types of icon
buttons: standard and contained.
* **Standard icon button:** By default icon buttons will not have a container.
* **Contained icon button:** Optionally, it is possible to have a container
around the icon.
See [Icon button examples](#icon-button-examples) section below for more
information.
### Usage
* Icon buttons should be used when a compact button is required, such as in a
toolbar.
* Icon buttons can take the form of a wide range of system icons.
* Ensure the meaning of the icon is unambiguous.
* Ensure that the tooltip describes the button’s action, rather than
the icon.
**Note:** The examples below show how to create an icon button using `Button`
which will be inflated to `MaterialButton` when using a Material theme. There is
a known performance issue where `MaterialButton` takes longer to initialize when
compared to `ImageButton` or `AppCompatImageButton`, in large part because
`MaterialButton` extends from `AppCompatButton` which supports more than just
icon buttons. Consider using those pure icon button alternatives if the extra
latency causes a noticeable issue for your app.
#### Icon button examples
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
#### Standard Icon button
The following example shows a standard icon button.
!["Standard icon button example for Android over a white background."](assets/buttons/icon-button-standard.png)
In the layout:
```xml
<Button
style="?attr/materialIconButtonStyle"
android:id="@+id/iconButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/standard_icon_btn_desc"
app:icon="@drawable/ic_icon_24dp"
/>
```
In code:
```kt
iconButton.addOnButtonCheckedListener { iconButton, checkedId, isChecked ->
// Respond to button selection
}
```
#### Filled Icon button
The following example shows a contained icon button that is filled.
!["Filled icon button example for Android over a white background."](assets/buttons/filled-icon-button.png)
In the layout:
```xml
<Button
style="?attr/materialIconButtonFilledStyle"
android:id="@+id/iconButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/filled_icon_btn_desc"
app:icon="@drawable/ic_icon_24dp"
/>
```
#### Filled Tonal Icon button
The following example shows a tonal icon button.
!["Filled tonal icon button example for Android over a white background."](assets/buttons/filled-tonal-icon-button.png)
In the layout:
```xml
<Button
style="?attr/materialIconButtonFilledTonalStyle"
android:id="@+id/iconButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/filled_tonal_icon_btn_desc"
app:icon="@drawable/ic_icon_24dp"
/>
```
#### Outlined Icon button
The following example shows an outlined icon button.
!["Outlined icon button example for Android over a white background."](assets/buttons/outlined-icon-button.png)
In the layout:
```xml
<Button
style="?attr/materialIconButtonOutlinedStyle"
android:id="@+id/iconButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/outlined_icon_btn_desc"
app:icon="@drawable/ic_icon_24dp"
/>
```
#### Styles and Theme attributes
Element | Style | Theme Attribute
---------------------------- | ------------------------------------------------- | ---------------
**Default style** | `Widget.Material3.Button.IconButton` | `?attr/materialIconButtonStyle`
**Filled Icon Button** | `Widget.Material3.Button.IconButton.Filled` | `?attr/materialIconButtonFilledStyle`
**Filled Tonal Icon Button** | `Widget.Material3.Button.IconButton.Filled.Tonal` | `?attr/materialIconButtonFilledTonalStyle`
**Outlined Icon Button** | `Widget.Material3.Button.IconButton.Outlined` | `?attr/materialIconButtonOutlinedStyle`
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).
## Optical Centering
Optical centering means to offset the `MaterialButton`’s contents (icon and/or
label) when the shape is asymmetric. Before optical centering, we only provided
centering with horizontally asymmetrical shapes.
To turn on optical centering for a given button, use
`setOpticalCenterEnabled(true)`. Optical centering is disabled by default. When
enabled, the shift amount of the icon and/or text is calculated as a value with
the fixed ratio to the difference between left corner size in dp and right
corner size in dp. The shift amount is applied to the padding start and padding
end.
## Theming buttons
Buttons support
[Material Theming](https://material.io/components/buttons/#theming) and can be
customized in terms of color, typography and shape.
### Button theming example
API and source code:
* `MaterialButton`
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
The following example shows text, outlined and filled button types with
Material Theming.
!["Button theming with three buttons - text, outlined and filled - with pink
color theming and cut corners."](assets/buttons/button-theming.png)
#### Implementing button theming
Use theme attributes and styles in `res/values/styles.xml` to add the theme to
all buttons. This affects other components:
```xml
<style name="Theme.App" parent="Theme.Material3.*">
...
<item name="colorPrimary">@color/shrine_pink_100</item>
<item name="colorOnPrimary">@color/shrine_pink_900</item>
<item name="textAppearanceLabelLarge">@style/TextAppearance.App.Button</item>
<item name="shapeCornerFamily">cut</item>
</style>
<style name="TextAppearance.App.Button" parent="TextAppearance.Material3.LabelLarge">
<item name="fontFamily">@font/rubik</item>
<item name="android:fontFamily">@font/rubik</item>
</style>
```
Use default style theme attributes, styles and theme overlays. This adds the
theme to all buttons but does not affect other components:
```xml
<style name="Theme.App" parent="Theme.Material3.*">
...
<item name="borderlessButtonStyle">@style/Widget.App.Button.TextButton</item>
<item name="materialButtonOutlinedStyle">@style/Widget.App.Button.OutlinedButton</item>
<item name="materialButtonStyle">@style/Widget.App.Button</item>
</style>
<style name="Widget.App.Button.TextButton" parent="Widget.Material3.Button.TextButton">
<item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
<item name="android:textAppearance">@style/TextAppearance.App.Button</item>
<item name="shapeAppearance">@style/ShapeAppearance.App.Button</item>
</style>
<style name="Widget.App.Button.OutlinedButton" parent="Widget.Material3.Button.OutlinedButton">
<item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
<item name="android:textAppearance">@style/TextAppearance.App.Button</item>
<item name="shapeAppearance">@style/ShapeAppearance.App.Button</item>
</style>
<style name="Widget.App.Button" parent="Widget.Material3.Button">
<item name="materialThemeOverlay">@style/ThemeOverlay.App.Button</item>
<item name="android:textAppearance">@style/TextAppearance.App.Button</item>
<item name="shapeAppearance">@style/ShapeAppearance.App.Button</item>
</style>
<style name="ThemeOverlay.App.Button.TextButton" parent="ThemeOverlay.Material3.Button.TextButton">
<item name="colorOnContainer">@color/shrine_pink_900</item>
</style>
<style name="ThemeOverlay.App.Button" parent="ThemeOverlay.Material3.Button">
<item name="colorContainer">@color/shrine_pink_100</item>
<item name="colorOnContainer">@color/shrine_pink_900</item>
</style>
<style name="ShapeAppearance.App.Button" parent="">
<item name="cornerFamily">cut</item>
<item name="cornerSize">4dp</item>
</style>
```
Use one of the styles in the layout. That will affect only this button:
```xml
<Button style="@style/Widget.App.Button".../>
```
Reference in New Issue View Git Blame Copy Permalink