Skip to content

Commit dbcc183

Browse files
Material Design Teamhunterstich
Material Design Team
authored and
hunterstich
committed
[Docs]Updated FABs and Extended FABs docs to make them more user friendly and added the M3 Expressive update section.
PiperOrigin-RevId: 777422106
1 parent dc96e10 commit dbcc183

18 files changed

+516
-282
lines changed

‎docs/components/ExtendedFloatingActionButton.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
<!--docs:
2+
title: "Extended floating action buttons"
3+
layout: detail
4+
section: components
5+
excerpt: "A floating action button (FAB) represents the primary action of a screen."
6+
iconId: button
7+
path: /catalog/floating-action-button/
8+
-->
9+
10+
# Extended floating action buttons (Extended FABs)
11+
12+
[Extended floating action buttons (extended FABs)](https://m3.material.io/components/extended-fab)
13+
help people take primary actions. There are three variants of the extended FAB.
14+
15+
<img src="assets/fabs/EFAB_types.png" alt="Types of extended FABs"/>
16+
17+
1. Small extended FAB
18+
2. Medium extended FAB
19+
3. Large extended FAB
20+
21+
**Note:** Images use various dynamic color schemes.
22+
23+
## Design & API documentation
24+
25+
* [Material 3 (M3) spec](https://m3.material.io/components/extended-fab/overview)
26+
* [API reference](https://developer.android.com/reference/com/google/android/material/floatingactionbutton/package-summary)
27+
28+
## Anatomy
29+
30+
<img src="assets/fabs/EFAB_anatomy.png" alt="Anatomy of extended FABs"/>
31+
32+
1. Container
33+
2. Text label
34+
3. Icon (Optional)
35+
36+
More details on anatomy items in the
37+
[component guidelines](https://m3.material.io/components/extended-fab/guidelines#1dc1f503-edff-4e3f-b2a6-c76cee1b8369).
38+
39+
## M3 Expressive update
40+
41+
Before you can use `Material3Expressive` component styles, follow the
42+
[`Material3Expressive` themes setup instructions](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md#material3expressive-themes).
43+
44+
![The deprecated original extended FAB and the small, medium, and large extended
45+
FABs from the expressive update.](assets/fabs/EFAB_expressive.png) The original
46+
extended FAB is replaced with a set of small, medium, and large extended FABs
47+
with new typography
48+
49+
The extended FAB now has three sizes: small, medium, and large, each with
50+
updated type styles. These align with the FAB sizes for an easier transition
51+
between FABs. The original extended FAB is being deprecated and should be
52+
replaced with the small extended FAB. Surface FABs are also being deprecated.
53+
[More on M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive)
54+
55+
**Types and naming:**
56+
57+
* Added new sizes
58+
* Small: 56dp
59+
* Medium: 80dp
60+
* Large: 96dp
61+
* Deprecated
62+
63+
* Original extended FAB (56dp)
64+
* Surface extended FAB
65+
66+
* Updates:
67+
68+
* Adjusted typography to be larger
69+
70+
## Key properties
71+
72+
### Container attributes
73+
74+
Element | Attribute | Related method(s) | Default value
75+
----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------
76+
**Color** | `app:backgroundTint` | `setBackgroundTintList`<br/>`getBackgroundTintList` | `?attr/colorPrimaryContainer` (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))
77+
**Stroke color** | `app:strokeColor` | `setStrokeColor`<br/>`getStrokeColor` | `null`
78+
**Stroke width** | `app:strokeWidth` | `setStrokeWidth`<br/>`getStrokeWidth` | `0dp`
79+
**Size** | `app:collapsedSize` | N/A |
80+
**Extend Strategy** | `app:extendStrategy` | N/A | `wrap_content`
81+
**Shape** | `app:shapeAppearance`<br/>`app:shapeAppearanceOverlay` | `setShapeAppearanceModel`<br/>`getShapeAppearanceModel` | `ShapeAppearanceOverlay.Material3.FloatingActionButton`<br/>
82+
**Elevation** | `app:elevation` | `setElevation`<br/>`getElevation` | `6dp`
83+
**Hovered/Focused elevation** | `app:hoveredFocusedTranslationZ` | N/A | `2dp`
84+
**Pressed elevation** | `app:pressedTranslationZ` | N/A | `6dp`
85+
**Ripple** | `app:rippleColor` | | variations of `?attr/colorOnPrimaryContainer`, 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)
86+
**Motion** | `app:showMotionSpec`<br>`app:hideMotionSpec`<br/>`extendMotionSpec`<br/>`shrinkMotionSpec` | `set*MotionSpec`<br/>`set*MotionSpecResource`<br/>`get*MotionSpec` | see [animators](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/res/animator)
87+
88+
### Icon attributes
89+
90+
Element | Attribute | Related method(s) | Default value
91+
--------------------------------- | ----------------- | --------------------------------------------------------- | -------------
92+
**Icon** | `app:icon` | `setIcon`<br/>`setIconResource`<br/>`getIcon` | `null`
93+
**Color** | `app:iconTint` | `setIconTint`<br/>`setIconTintResource`<br/>`getIconTint` | `?attr/colorOnPrimaryContainer` (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))
94+
**Size** | `app:iconSize` | `setIconSize`<br/>`getIconSize` | `24dp`
95+
**Padding between icon and text** | `app:iconPadding` | `setIconPadding`<br/>`getIconPadding` | `12dp`
96+
97+
### Text label
98+
99+
Element | Attribute | Related method(s) | Default value
100+
-------------- | ------------------------ | --------------------------------- | -------------
101+
**Text label** | `android:text` | `setText`<br/>`getText` | `null`
102+
**Color** | `android:textColor` | `setTextColor`<br/>`getTextColor` | `?attr/colorPrimaryContainer` (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))
103+
**Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceLabelLarge`
104+
105+
### Styles
106+
107+
Element | Style | Theme attribute
108+
----------------------------------------- | ------------------------------------------------------------ | ---------------
109+
**Default style** | `Widget.Material3.ExtendedFloatingActionButton.Icon.Primary` | `?attr/extendedFloatingActionButtonStyle`
110+
**Text-only when**<br/>**extended style** | `Widget.Material3.ExtendedFloatingActionButton.Primary` | `?attr/extendedFloatingActionButtonPrimaryStyle`
111+
112+
See the full list of
113+
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/res/values/styles.xml)
114+
and
115+
[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/res/values/attrs.xml).
116+
117+
## Variants of extended FAB
118+
119+
There are three types of extended FABs: small, medium, and large.
120+
121+
![EFAB sizes](assets/fabs/EFAB_sizes.png)
122+
123+
Choose an appropriately-sized extended FAB to add the right amount of emphasis
124+
for an action.
125+
126+
In compact windows with one prominent action, the **large extended FAB** can be
127+
appropriate.
128+
129+
In larger window sizes, use a **medium** or **large extended FAB**.
130+
131+
## Code implementation
132+
133+
Before you can use Material extended FABs, you need to add a dependency to the
134+
Material Components for Android library. For more information, go to the
135+
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
136+
page.
137+
138+
**Note:** If the `FloatingActionButton` is a child of a `CoordinatorLayout`, you
139+
get certain behaviors for free. It will automatically shift so that any
140+
displayed `Snackbar`s do not cover it, and will automatically hide when covered
141+
by an `AppBarLayout` or `BottomSheetBehavior`.
142+
143+
### Adding extended FAB
144+
145+
The extended FAB is wider, and it includes a text label.
146+
147+
**Note:** `ExtendedFloatingActionButton` is a child class of
148+
[`MaterialButton`](Button.md), rather than `FloatingActionButton`. This means
149+
that several attributes which are applicable to `FloatingActionButton` have
150+
different naming in `ExtendedFloatingActionButton`. For example,
151+
`FloatingActionButton` uses `app:srcCompat` to set the icon drawable, whereas
152+
`ExtendedFloatingActionButton` uses `app:icon`. See the
153+
[attributes tables](#key-properties) for more details.
154+
155+
API and source code:
156+
157+
* `ExtendedFloatingActionButton`
158+
* [Class description](https://developer.android.com/reference/com/google/android/material/floatingactionbutton/ExtendedFloatingActionButton)
159+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/ExtendedFloatingActionButton.java)
160+
161+
The following example shows an extended FAB with a plus icon.
162+
163+
<img src="assets/fabs/fab_extended.png" alt="Purple FAB with plus icon and Extended label" height="400"/>
164+
165+
In the layout:
166+
167+
```xml
168+
<androidx.coordinatorlayout.widget.CoordinatorLayout
169+
...
170+
>
171+
172+
<!-- Main content -->
173+
174+
<com.google.android.material.floatingactionbutton.ExtendedFloatingActionButton
175+
android:id="@+id/extended_fab"
176+
android:layout_width="wrap_content"
177+
android:layout_height="wrap_content"
178+
android:layout_margin="16dp"
179+
android:layout_gravity="bottom|end"
180+
android:contentDescription="@string/extended_fab_content_desc"
181+
android:text="@string/extended_fab_label"
182+
app:icon="@drawable/ic_plus_24px"/>
183+
184+
</androidx.coordinatorlayout.widget.CoordinatorLayout>
185+
```
186+
187+
In code:
188+
189+
```kt
190+
extendedFab.setOnClickListener {
191+
// Respond to Extended FAB click
192+
}
193+
```
194+
195+
### Making extended FABs accessible
196+
197+
You should set a content description on a FAB via the
198+
`android:contentDescription` attribute or `setContentDescription` method so that
199+
screen readers like TalkBack are able to announce their purpose or action. Text
200+
rendered in Extended FABs is automatically provided to accessibility services,
201+
so additional content labels are usually unnecessary.
202+
203+
### Animating visibility of extended FAB
204+
205+
Use the `show` and `hide` methods to animate the visibility of an
206+
`ExtendedFloatingActionButton`. The show animation grows the widget and fades it
207+
in, while the hide animation shrinks the widget and fades it out.
208+
209+
```kt
210+
// To show:
211+
fab.show()
212+
// To hide:
213+
fab.hide()
214+
```
215+
216+
### Extending and shrinking extended FAB
217+
218+
Use the `extend` and `shrink` methods to animate showing and hiding the text of
219+
an `ExtendedFloatingActionButton`. The extend animation extends the FAB to show
220+
the text and the icon. The shrink animation shrinks the FAB to show just the
221+
icon.
222+
223+
```kt
224+
// To extend:
225+
extendedFab.extend()
226+
// To shrink:
227+
extendedFab.shrink()
228+
```
229+
230+
## Customizing extended FABs
231+
232+
### Theming extended FABs
233+
234+
#### Extended FAB theming example
235+
236+
API and source code:
237+
238+
* `ExtendedFloatingActionButton`
239+
* [Class description](https://developer.android.com/reference/com/google/android/material/floatingactionbutton/ExtendedFloatingActionButton)
240+
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingactionbutton/ExtendedFloatingActionButton.java)
241+
242+
The following example shows a regular, small, and extended FAB with Material
243+
Theming.
244+
245+
!["3 square pink FABs with cut corners with brown plus icons: 56dp, 40dp, 56dp
246+
with "Extended" label"](assets/fabs/fab_theming.png)
247+
248+
##### Implementing FAB theming
249+
250+
Use theme attributes and styles in `res/values/styles.xml` to add themes to all
251+
FABs. This affects other components:
252+
253+
```xml
254+
<style name="Theme.App" parent="Theme.Material3.*">
255+
...
256+
<item name="colorPrimaryContainer">@color/purple_500</item>
257+
<item name="colorOnPrimaryContainer">@color/purple_700</item>
258+
</style>
259+
```
260+
261+
Use a default style theme attribute, styles and a theme overlay. This themes all
262+
FABs in your app but does not affect other components:
263+
264+
```xml
265+
<style name="Theme.App" parent="Theme.Material3.*">
266+
...
267+
<item name="extendedFloatingActionButtonStyle">@style/Widget.App.ExtendedFloatingActionButton</item>
268+
<item name="floatingActionButtonStyle">@style/Widget.App.FloatingActionButton</item>
269+
</style>
270+
271+
<style name="Widget.App.ExtendedFloatingActionButton" parent="Widget.Material3.ExtendedFloatingActionButton.Icon.Primary">
272+
<item name="materialThemeOverlay">@style/ThemeOverlay.App.FloatingActionButton</item>
273+
</style>
274+
275+
<style name="Widget.App.FloatingActionButton" parent="Widget.Material3.FloatingActionButton.Primary">
276+
<item name="materialThemeOverlay">@style/ThemeOverlay.App.FloatingActionButton</item>
277+
</style>
278+
279+
<style name="ThemeOverlay.App.FloatingActionButton" parent="">
280+
<item name="colorContainer">@color/purple_500</item>
281+
<item name="colorOnContainer">@color/purple_700</item>
282+
</style>
283+
```
284+
285+
Use one of the styles in the layout. That affects only this FAB:
286+
287+
```xml
288+
<com.google.android.material.floatingactionbutton.FloatingActionButton
289+
...
290+
style="@style/Widget.App.FloatingActionButton"
291+
/>
292+
```
293+
294+
### Sizing extended FABs
295+
296+
The `ExtendedFloatingActionButton` will be sized dynamically based on its
297+
contents (icon and label) and paddings. If a bigger fixed size is preferred, you
298+
may use `android:minWidth` and `android:minHeight` attributes.
299+
300+
In Material 3 themes, styles in 3 different sizes are provided:
301+
302+
* Small - `?attr/extendedFloatingActionButtonSmallStyle` (or
303+
`?attr/extendedFloatingActionButton`,
304+
`?attr/extendedFloatingActionButtonPrimaryStyle`,
305+
`?attr/extendedFloatingActionButtonSecondaryStyle`,
306+
`?attr/extendedFloatingActionButtonTertiaryStyle`,
307+
`?attr/extendedFloatingActionButtonSurfaceStyle`)
308+
* Medium - `?attr/extendedFloatingActionButtonMediumStyle`
309+
* Large - `?attr/extendedFloatingActionButtonLargeStyle`
310+
311+
**Note:** If you are using the extending/collapsing feature with custom height,
312+
please also consider to set the `collapsedSize` attribute to the same height.

0 commit comments

Comments
 (0)