docs/components/IconButton.md
Icon buttons help people take minor actions with one tap. There are two variants of icon buttons.
Note: Images use various dynamic color schemes.
More details on anatomy items in the component guidelines.
Before you can use Material3Expressive component styles, follow the
Material3Expressive themes setup instructions.
Icon buttons now have a wider variety of shapes and sizes, changing shape when selected. When placed in button groups, icon buttons interact with each other when pressed. More on M3 Expressive
Types and naming:
Shapes:
Sizes:
Widths:
| Default <div style="width:250px"></div> | Checked <div style="width:250px"></div> | Unchecked <div style="width:250px"></div> |
|---|---|---|
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"/>
| Default <div style="width:250px"></div> | Checked <div style="width:250px"></div> | Unchecked <div style="width:250px"></div> |
|---|---|---|
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.{Small}.Square"/>
There are five icon button size variants: Extra small, small, medium, large, and extra large.
<details><summary><h5>Extra small</h5></summary>Note: Images below show the icon only buttons in different sizes relatively. The actual sizes in px on mobile devices depends on the screen pixel density.
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.Xsmall"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.Small"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.Medium"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.Large"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.Xlarge"/>
Each icon button has three width options: narrow, uniform (default), and wide.
<details><summary><h5>Narrow</h5></summary><Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.{Small}.Narrow"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"/>
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:icon="@drawable/icon"
app:materialSizeOverlay="@style/SizeOverlay.Material3Expressive.Button.IconButton.{Small}.Wide"/>
| 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 and attrs.
There are four icon button color styles, in order of emphasis:
For the highest emphasis, use the filled style. For the lowest emphasis, use standard.
Single icons can be used for additional, supplementary actions. They're best for areas of a compact layout, such as a toolbar.
The default dimensions allow for a touch target of 48dp. If using an icon
bigger than the default size, the padding dimensions should be adjusted to
preserve the circular shape. android:inset* dimensions can also be adjusted if
less empty space is desired around the icon.
Always include an android:contentDescription so that icon only buttons are
readable for screen readers.
Standard, filled unselected, filled selected, filled tonal, and outlined icon buttons
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.
| Default <div style="width:250px"></div> | Checked <div style="width:250px"></div> | Unchecked <div style="width:250px"></div> |
|---|---|---|
By default, the standard icon only button is uncheckable. To make it checkable,
enable the android:checkable attribute in style or layout.
<Button
style="?attr/materialIconButtonFilledStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/icon_description"
android:checkable="true"
app:icon="@drawable/icon"/>
| Default <div style="width:250px"></div> | Checked <div style="width:250px"></div> | Unchecked <div style="width:250px"></div> |
|---|---|---|
By default, the standard icon only button is uncheckable. To make it checkable,
enable the android:checkable attribute in style or layout.
<Button
style="?attr/materialIconButtonStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/icon_description"
android:checkable="true"
app:icon="@drawable/icon"/>
| Default <div style="width:250px"></div> | Checked <div style="width:250px"></div> | Unchecked <div style="width:250px"></div> |
|---|---|---|
By default, the standard icon only button is uncheckable. To make it checkable,
enable the android:checkable attribute in style or layout.
<Button
style="?attr/materialIconButtonFilledTonalStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/icon_description"
android:checkable="true"
app:icon="@drawable/icon"/>
| Default <div style="width:250px"></div> | Checked <div style="width:250px"></div> | Unchecked <div style="width:250px"></div> |
|---|---|---|
By default, the standard icon only button is uncheckable. To make it checkable,
enable the android:checkable attribute in style or layout.
<Button
style="?attr/materialIconButtonOutlinedStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:contentDescription="@string/icon_description"
android:checkable="true"
app:icon="@drawable/icon"/>
Toggle icon buttons can represent binary actions that can be toggled on and off, such as favorite or bookmark.
Each icon button has as an optional toggle behavior, which lets people select and unselect the button. Toggle buttons remain highlighted when selected, and are styled differently than the default, non-toggle buttons.
Toggle buttons should use an outlined icon when unselected, and a filled version of the icon when selected.
In toggle buttons, use the outlined style of an icon for the unselected state, and the filled style for the selected state.
The following example shows a toggle icon button.
Create file res/drawable/toggle_icon_button_selector.xml to include both
outlined and filled icons for the toggle icon button:
<selector xmlns:android="http://schemas.android.com/apk/res/android">
<item android:state_checked="true" android:drawable="@drawable/star_filled" />
<item android:drawable="@drawable/star_outline" /> </selector>
<com.google.android.material.button.MaterialButton
android:id="@+id/toggleIconButton"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
style="@style/Widget.Material3.Button.IconButton.Standard"
app:icon="@drawable/toggle_icon_button_selector"
app:iconTint="?attr/colorAccent"
android:contentDescription="Toggle icon button"
android:checkable="true"/>
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.
Buttons support the customization of color, typography, and shape.
API and source code:
MaterialButton
The following example shows text, outlined and filled button types with Material theming.
Use theme attributes and styles in res/values/styles.xml to add the theme to
all buttons. This affects other components:
<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:
<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:
<Button style="@style/Widget.App.Button".../>
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.