Skip to content

Commit b84b335

Browse files
Material Design Teamhunterstich
Material Design Team
authored and
hunterstich
committed
[Docs] Updated Button doc to make it more user friendly.
We have kept the Button file as the navigation file and have split the content into the following five pages: 1. Common button 2. Button group 3. Toggle button group 4. Icon button 5. Split button This structure is inline with the M3 spec doc. PiperOrigin-RevId: 777529719
1 parent 362c64c commit b84b335

29 files changed

+2336
-1468
lines changed

‎docs/components/Button.md‎

Lines changed: 13 additions & 1468 deletions
Large diffs are not rendered by default.

‎docs/components/ButtonGroup.md‎

Lines changed: 499 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/components/CommonButton.md‎

Lines changed: 824 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/components/IconButton.md‎

Lines changed: 364 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,364 @@
1+
<!--docs:
2+
title: "Icon buttons"
3+
layout: detail
4+
section: components
5+
excerpt: "A customizable button component with updated visual styles."
6+
iconId: materialbutton
7+
path: /catalog/buttons/
8+
-->
9+
10+
# Icon buttons
11+
12+
[Icon buttons](https://m3.material.io/components/icon-buttons/overview) help
13+
people take minor actions with one tap. There are two variants of icon buttons.
14+
15+
![2 types of icon buttons](assets/buttons/iconbuttons_types.png)
16+
17+
1. Default icon button
18+
2. Toggle icon button
19+
20+
**Note:** Images use various dynamic color schemes.
21+
22+
## Design & API documentation
23+
24+
* [Material 3 (M3) spec](https://m3.material.io/components/icon-buttons/overview)
25+
* [API reference](https://developer.android.com/reference/com/google/android/material/button/package-summary)
26+
27+
## Anatomy
28+
29+
![Anatomy of an icon button ](assets/buttons/iconbuttons_anatomy.png)
30+
31+
1. Icon
32+
2. Container
33+
34+
More details on anatomy items in the
35+
[component guidelines](https://m3.material.io/components/icon-buttons/guidelines#1f6f6121-e403-4d82-aa6a-5ab276f4bc4c).
36+
37+
## M3 Expressive update
38+
39+
Before you can use `Material3Expressive` component styles, follow the
40+
[`Material3Expressive` themes setup instructions](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md#material3expressive-themes).
41+
42+
<img src="assets/buttons/iconbuttons_expressive.png" alt="Icon buttons can vary in size, shape, and width." height="400"/>
43+
44+
1. Five sizes
45+
2. Two shapes
46+
3. Three widths
47+
48+
Icon buttons now have a wider variety of shapes and sizes, changing shape when
49+
selected. When placed in button groups, icon buttons interact with each other
50+
when pressed.
51+
[More on M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive)
52+
53+
**Types and naming:**
54+
55+
* Default and toggle (selection)
56+
* Color styles are now configurations. (filled, tonal, outlined, standard)
57+
58+
**Shapes:**
59+
60+
* Round and square options
61+
* Shape morphs when pressed
62+
* Shape morphs when selected
63+
64+
**Sizes:**
65+
66+
* Extra small
67+
* Small (default)
68+
* Medium
69+
* Large
70+
* Extra large
71+
72+
**Widths:**
73+
74+
* Narrow
75+
* Default
76+
* Wide
77+
78+
## Key properties
79+
80+
### Styles and theme attributes
81+
82+
Element | Style | Theme Attribute
83+
---------------------------- | ------------------------------------------------- | ---------------
84+
**Default style** | `Widget.Material3.Button.IconButton` | `?attr/materialIconButtonStyle`
85+
**Filled Icon Button** | `Widget.Material3.Button.IconButton.Filled` | `?attr/materialIconButtonFilledStyle`
86+
**Filled Tonal Icon Button** | `Widget.Material3.Button.IconButton.Filled.Tonal` | `?attr/materialIconButtonFilledTonalStyle`
87+
**Outlined Icon Button** | `Widget.Material3.Button.IconButton.Outlined` | `?attr/materialIconButtonOutlinedStyle`
88+
89+
See the full list of
90+
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/styles.xml)
91+
and
92+
[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/res/values/attrs.xml).
93+
94+
## Variants of icon buttons
95+
96+
### Default icon button
97+
98+
* Default icon buttons can open other elements, such as a menu or search.
99+
* Default icon buttons should use filled icons.
100+
101+
### Toggle icon button
102+
103+
* Toggle icon buttons can represent binary actions that can be toggled on and
104+
off, such as favorite or bookmark.
105+
106+
* Each icon button has as an optional toggle behavior, which lets people
107+
select and unselect the button. Toggle buttons remain highlighted when
108+
selected, and are styled differently than the default, non-toggle buttons.
109+
110+
* Toggle buttons should use an outlined icon when unselected, and a filled
111+
version of the icon when selected.
112+
113+
**There are four icon button color styles, in order of emphasis:**
114+
115+
1. Filled
116+
2. Tonal
117+
3. Outlined
118+
4. Standard
119+
120+
For the highest emphasis, use the filled style. For the lowest emphasis, use
121+
standard.
122+
123+
![Diagram of default and toggle icon buttons in 4 color styles.](assets/buttons/iconbuttons_color.png)
124+
125+
The default (left) and toggle (right) icon buttons are available in all four
126+
color styles
127+
128+
## Code implementation
129+
130+
**Note:** The examples below show how to create an icon button using `Button`
131+
which will be inflated to `MaterialButton` when using a Material theme. There is
132+
a known performance issue where `MaterialButton` takes longer to initialize when
133+
compared to `ImageButton` or `AppCompatImageButton`, in large part because
134+
`MaterialButton` extends from `AppCompatButton` which supports more than just
135+
icon buttons. Consider using those pure icon button alternatives if the extra
136+
latency causes a noticeable issue for your app.
137+
138+
![Code implementation for icon buttons.](assets/buttons/iconbuttons_codeimplementation.png)
139+
Standard, filled unselected, filled selected, filled tonal, and outlined icon
140+
buttons
141+
142+
### Adding standard icon button
143+
144+
The following example shows a standard icon button.
145+
146+
!["Standard icon button example for Android over a white background."](assets/buttons/icon-button-standard.png)
147+
148+
In the layout:
149+
150+
```xml
151+
<Button
152+
style="?attr/materialIconButtonStyle"
153+
android:id="@+id/iconButton"
154+
android:layout_width="wrap_content"
155+
android:layout_height="wrap_content"
156+
android:contentDescription="@string/standard_icon_btn_desc"
157+
app:icon="@drawable/ic_icon_24dp"
158+
/>
159+
```
160+
161+
In code:
162+
163+
```kt
164+
iconButton.addOnButtonCheckedListener { iconButton, checkedId, isChecked ->
165+
// Respond to button selection
166+
}
167+
```
168+
169+
### Adding filled icon button
170+
171+
The following example shows a contained icon button that is filled.
172+
173+
!["Filled icon button example for Android over a white background."](assets/buttons/filled-icon-button.png)
174+
175+
In the layout:
176+
177+
```xml
178+
<Button
179+
style="?attr/materialIconButtonFilledStyle"
180+
android:id="@+id/iconButton"
181+
android:layout_width="wrap_content"
182+
android:layout_height="wrap_content"
183+
android:contentDescription="@string/filled_icon_btn_desc"
184+
app:icon="@drawable/ic_icon_24dp"
185+
/>
186+
```
187+
188+
### Adding filled tonal icon button
189+
190+
The following example shows a tonal icon button.
191+
192+
!["Filled tonal icon button example for Android over a white background."](assets/buttons/filled-tonal-icon-button.png)
193+
194+
In the layout:
195+
196+
```xml
197+
<Button
198+
style="?attr/materialIconButtonFilledTonalStyle"
199+
android:id="@+id/iconButton"
200+
android:layout_width="wrap_content"
201+
android:layout_height="wrap_content"
202+
android:contentDescription="@string/filled_tonal_icon_btn_desc"
203+
app:icon="@drawable/ic_icon_24dp"
204+
/>
205+
```
206+
207+
### Adding outlined icon button
208+
209+
The following example shows an outlined icon button.
210+
211+
!["Outlined icon button example for Android over a white background."](assets/buttons/outlined-icon-button.png)
212+
213+
In the layout:
214+
215+
```xml
216+
<Button
217+
style="?attr/materialIconButtonOutlinedStyle"
218+
android:id="@+id/iconButton"
219+
android:layout_width="wrap_content"
220+
android:layout_height="wrap_content"
221+
android:contentDescription="@string/outlined_icon_btn_desc"
222+
app:icon="@drawable/ic_icon_24dp"
223+
/>
224+
```
225+
226+
### Adding toggle icon button
227+
228+
In toggle buttons, use the outlined style of an icon for the unselected state,
229+
and the filled style for the selected state.
230+
231+
The following example shows a toggle icon button.
232+
233+
Create file `res/drawable/toggle_icon_button_selector.xml` to include both
234+
outlined and filled icons for the toggle icon button:
235+
236+
```xml
237+
<selector xmlns:android="http://schemas.android.com/apk/res/android">
238+
<item android:state_checked="true" android:drawable="@drawable/star_filled" />
239+
<item android:drawable="@drawable/star_outline" /> </selector>
240+
241+
<com.google.android.material.button.MaterialButton
242+
android:id="@+id/toggleIconButton"
243+
android:layout_width="wrap_content"
244+
android:layout_height="wrap_content"
245+
style="@style/Widget.Material3.Button.IconButton.Standard"
246+
app:icon="@drawable/toggle_icon_button_selector"
247+
app:iconTint="?attr/colorAccent"
248+
android:contentDescription="Toggle icon button"
249+
android:checkable="true"/>
250+
```
251+
252+
### Making buttons accessible
253+
254+
Buttons support content labeling for accessibility and are readable by most
255+
screen readers, such as TalkBack. Text rendered in buttons is automatically
256+
provided to accessibility services. Additional content labels are usually
257+
unnecessary.
258+
259+
For more information on content labels, go to the
260+
[Android accessibility help guide](https://support.google.com/accessibility/android/answer/7158690).
261+
262+
## Customizing icon buttons
263+
264+
### Theming buttons
265+
266+
Buttons support the customization of color, typography, and shape.
267+
268+
#### Button theming example
269+
270+
API and source code:
271+
272+
* `MaterialButton`
273+
* [Class description](https://developer.android.com/reference/com/google/android/material/button/MaterialButton)
274+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/button/MaterialButton.java)
275+
276+
The following example shows text, outlined and filled button types with Material
277+
theming.
278+
279+
!["Button theming with three buttons - text, outlined and filled - with pink
280+
color theming and cut corners."](assets/buttons/button-theming.png)
281+
282+
##### Implementing button theming
283+
284+
Use theme attributes and styles in `res/values/styles.xml` to add the theme to
285+
all buttons. This affects other components:
286+
287+
```xml
288+
<style name="Theme.App" parent="Theme.Material3.*">
289+
...
290+
<item name="colorPrimary">@color/shrine_pink_100</item>
291+
<item name="colorOnPrimary">@color/shrine_pink_900</item>
292+
<item name="textAppearanceLabelLarge">@style/TextAppearance.App.Button</item>
293+
<item name="shapeCornerFamily">cut</item>
294+
</style>
295+
296+
<style name="TextAppearance.App.Button" parent="TextAppearance.Material3.LabelLarge">
297+
<item name="fontFamily">@font/rubik</item>
298+
<item name="android:fontFamily">@font/rubik</item>
299+
</style>
300+
```
301+
302+
Use default style theme attributes, styles and theme overlays. This adds the
303+
theme to all buttons but does not affect other components:
304+
305+
```xml
306+
<style name="Theme.App" parent="Theme.Material3.*">
307+
...
308+
<item name="borderlessButtonStyle">@style/Widget.App.Button.TextButton</item>
309+
<item name="materialButtonOutlinedStyle">@style/Widget.App.Button.OutlinedButton</item>
310+
<item name="materialButtonStyle">@style/Widget.App.Button</item>
311+
</style>
312+
313+
<style name="Widget.App.Button.TextButton" parent="Widget.Material3.Button.TextButton">
314+
<item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
315+
<item name="android:textAppearance">@style/TextAppearance.App.Button</item>
316+
<item name="shapeAppearance">@style/ShapeAppearance.App.Button</item>
317+
</style>
318+
319+
<style name="Widget.App.Button.OutlinedButton" parent="Widget.Material3.Button.OutlinedButton">
320+
<item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
321+
<item name="android:textAppearance">@style/TextAppearance.App.Button</item>
322+
<item name="shapeAppearance">@style/ShapeAppearance.App.Button</item>
323+
</style>
324+
325+
<style name="Widget.App.Button" parent="Widget.Material3.Button">
326+
<item name="materialThemeOverlay">@style/ThemeOverlay.App.Button</item>
327+
<item name="android:textAppearance">@style/TextAppearance.App.Button</item>
328+
<item name="shapeAppearance">@style/ShapeAppearance.App.Button</item>
329+
</style>
330+
331+
<style name="ThemeOverlay.App.Button.TextButton" parent="ThemeOverlay.Material3.Button.TextButton">
332+
<item name="colorOnContainer">@color/shrine_pink_900</item>
333+
</style>
334+
335+
<style name="ThemeOverlay.App.Button" parent="ThemeOverlay.Material3.Button">
336+
<item name="colorContainer">@color/shrine_pink_100</item>
337+
<item name="colorOnContainer">@color/shrine_pink_900</item>
338+
</style>
339+
340+
<style name="ShapeAppearance.App.Button" parent="">
341+
<item name="cornerFamily">cut</item>
342+
<item name="cornerSize">4dp</item>
343+
</style>
344+
```
345+
346+
Use one of the styles in the layout. That will affect only this button:
347+
348+
```xml
349+
350+
<Button style="@style/Widget.App.Button".../>
351+
```
352+
353+
### Optical centering
354+
355+
Optical centering means to offset the `MaterialButton`’s contents (icon and/or
356+
label) when the shape is asymmetric. Before optical centering, we only provided
357+
centering with horizontally asymmetrical shapes.
358+
359+
To turn on optical centering for a given button, use
360+
`setOpticalCenterEnabled(true)`. Optical centering is disabled by default. When
361+
enabled, the shift amount of the icon and/or text is calculated as a value with
362+
the fixed ratio to the difference between left corner size in dp and right
363+
corner size in dp. The shift amount is applied to the padding start and padding
364+
end.

0 commit comments

Comments
 (0)