diff --git a/catalog/java/io/material/catalog/button/res/layout/cat_buttons_fragment.xml b/catalog/java/io/material/catalog/button/res/layout/cat_buttons_fragment.xml
index 1857f30dfaa..a8964d1d4b6 100644
--- a/catalog/java/io/material/catalog/button/res/layout/cat_buttons_fragment.xml
+++ b/catalog/java/io/material/catalog/button/res/layout/cat_buttons_fragment.xml
@@ -132,12 +132,52 @@
android:text="@string/cat_outlined_icon_btn_text"
android:textSize="16sp"/>
-
+ android:paddingTop="8dp"
+ android:paddingBottom="8dp"
+ android:gravity="center_horizontal"
+ android:orientation="horizontal">
+
+
+
+
+
+
+
+
+
+
+
Filled buttons
Outlined buttons
Icon only buttons
+ Standard
+ Filled
Button clicked
Done
diff --git a/docs/components/Button.md b/docs/components/Button.md
index f3d34fca2b1..fec67f790a2 100644
--- a/docs/components/Button.md
+++ b/docs/components/Button.md
@@ -820,7 +820,15 @@ icon.setOnCheckedChangeListener { checkBox, isChecked ->
## Icon button
[Icon buttons](https://material.io/components/buttons/#icon-buttons) help users
-take supplementary actions with a single tap.
+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
@@ -839,6 +847,8 @@ API and source code:
* [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)
@@ -862,13 +872,29 @@ iconButton.addOnButtonCheckedListener { iconButton, checkedId, isChecked ->
}
```
-#### Styles & Theme attributes
+#### Filled Icon button
-Element | Style
------------------ | ------------------------------------
-**Default style** | `Widget.Material3.Button.IconButton`
+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
+
+```
+
+#### Styles & Theme attributes
-Default style theme attribute: `?attr/materialIconButtonStyle`
+Element | Style | Theme Attribute
+---------------------- | ------------------------------------------- | ---------------
+**Default style** | `Widget.Material3.Button.IconButton` | `?attr/materialIconButtonStyle`
+**Filled Icon Button** | `Widget.Material3.Button.IconButton.Filled` | `?attr/materialIconButtonFilledStyle`
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)
diff --git a/docs/components/assets/buttons/filled-icon-button.png b/docs/components/assets/buttons/filled-icon-button.png
new file mode 100644
index 00000000000..851cf386331
Binary files /dev/null and b/docs/components/assets/buttons/filled-icon-button.png differ
diff --git a/lib/java/com/google/android/material/button/res-public/values/public.xml b/lib/java/com/google/android/material/button/res-public/values/public.xml
index 368287ffb4a..f754f199a83 100644
--- a/lib/java/com/google/android/material/button/res-public/values/public.xml
+++ b/lib/java/com/google/android/material/button/res-public/values/public.xml
@@ -27,6 +27,7 @@
+
@@ -51,6 +52,7 @@
+
diff --git a/lib/java/com/google/android/material/button/res/values/attrs.xml b/lib/java/com/google/android/material/button/res/values/attrs.xml
index 810d909679b..f5405d54ce3 100644
--- a/lib/java/com/google/android/material/button/res/values/attrs.xml
+++ b/lib/java/com/google/android/material/button/res/values/attrs.xml
@@ -21,6 +21,8 @@
+
+
diff --git a/lib/java/com/google/android/material/button/res/values/styles.xml b/lib/java/com/google/android/material/button/res/values/styles.xml
index 1e0be115144..220f7c8be50 100644
--- a/lib/java/com/google/android/material/button/res/values/styles.xml
+++ b/lib/java/com/google/android/material/button/res/values/styles.xml
@@ -274,6 +274,12 @@
- @dimen/m3_btn_icon_only_icon_padding
+
+