Skip to content

Latest commit

 

History

History
433 lines (316 loc) · 20.2 KB

FloatingActionButton.md

File metadata and controls

433 lines (316 loc) · 20.2 KB
Raw

Floating action buttons

A floating action button (FAB) represents the primary action of a screen.

"A FAB on a screen"

Contents

Using FABs

A FAB performs the primary, or most common, action on a screen. It appears in front of all screen content, typically as a circular shape with an icon in its center.

Before you can use Material FABs, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Note: If the FloatingActionButton is a child of a CoordinatorLayout, you get certain behaviors for free. It will automatically shift so that any displayed Snackbars do not cover it, and will automatially hide when covered by an AppBarLayout or BottomSheetBehavior.

Making FABs accessible

You should set a content description on a FAB via the android:contentDescription attribute or setContentDescription method so that screen readers like TalkBack are able to announce their purpose or action. Text rendered in Extended FABs is automatically provided to accessibility services, so additional content labels are usually unnecessary.

Visibility

Use the show and hide methods to animate the visibility of a FloatingActionButton or an ExtendedFloatingActionButton. The show animation grows the widget and fades it in, while the hide animation shrinks the widget and fades it out.

// To show:
fab.show()
// To hide:
fab.hide()

Extending and Shrinking

Use the extend and shrink methods to animate showing and hiding the text of an ExtendedFloatingActionButton. The extend animation extends the FAB to show the text and the icon. The shrink animation shrinks the FAB to show just the icon.

// To extend:
extendedFab.extend()
// To shrink:
extendedFab.shrink()

Sizing FABs

The FloatingActionButton can be sized either by using the discrete sizing modes or a custom size.

There are three app:fabSize modes:

  • normal - the normal sized button, 56dp.
  • mini - the mini sized button, 40dp.
  • auto (default) - the button size will change based on the window size. For small sized windows (largest screen dimension < 470dp) this will select a mini sized button, and for larger sized windows it will select a normal sized button.

Or, you can set a custom size via the app:fabCustomSize attribute. If set, app:fabSize will be ignored, unless the custom size is cleared via the clearCustomSize method.

Types

There are three types of FABS: 1. Regular FABs, 2. Mini FABs, 3. Extended FABs

FAB types

Regular FABs

Regular FABs are FABs that are not expanded and are a regular size.

API and source code:

Regular FAB example

The following example shows a regular FAB with a plus icon.

56dp round teal FAB with black plus icon

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...
    android:layout_width="match_parent"
    android:layout_height="match_parent">

  <!-- Main content -->

  <com.google.android.material.floatingactionbutton.FloatingActionButton
      android:id="@+id/floating_action_button"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:layout_gravity="bottom|right"
      android:layout_margin="16dp"
      android:contentDescription="@string/fab_content_desc"
      app:srcCompat="@drawable/ic_plus_24"/>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

In code:

fab.setOnClickListener {
    // Respond to FAB click
}

Anatomy

Regular FAB anatomy diagram

A regular FAB has a container and an icon.

  1. Container
  2. Icon

Mini FABs

A mini FAB should be used on smaller screens.

Mini FABs can also be used to create visual continuity with other screen elements.

API and source code:

Mini FAB example

The following example shows a mini FAB with a plus icon.

40dp round teal FAB with black plus icon

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...
    >

  <!-- Main content -->

  <com.google.android.material.floatingactionbutton.FloatingActionButton
      ...
      app:fabSize="mini"/>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

In code:

fab.setOnClickListener {
    // Respond to FAB click
}

Anatomy

Mini FAB anatomy diagram

A mini FAB has a container and an icon.

  1. Container
  2. Icon

Regular and mini FAB key properties

Container attributes

Element Attribute Related method(s) Default value
Color app:backgroundTint setBackgroundTintList
getBackgroundTintList		 ?attr/colorSecondary (see all states)
Stroke app:borderWidth N/A 0.5dp
Size app:fabSize
app:fabCustomSize		 setSize
setCustomSize
clearCustomSize
getSize
getCustomSize		 auto
Shape shapeAppearance
shapeAppearanceOverlay		 setShapeAppearanceModel
getShapeAppearanceModel		 ?attr/shapeAppearanceSmallComponent
Elevation app:elevation setElevation
getCompatElevation		 6dp
Hovered/Focused elevation app:hoveredFocusedTranslationZ setCompatHoveredFocusedTranslationZ
getCompatHoveredFocusedTranslationZ		 2dp
Pressed elevation app:pressedTranslationZ setCompatPressedTranslationZ
getCompatPressedTranslationZ		 6dp
Ripple app:rippleColor setRippleColor
getRippleColor
getRippleColorStateList		 variations of ?attr/colorOnSecondary, see all states
Motion app:showMotionSpec
app:hideMotionSpec		 set*MotionSpec
set*MotionSpecResource
get*MotionSpec		 see animators

Icon attributes

Element Attribute Related method(s) Default value
Icon app:srcCompat setImageDrawable
setImageResource
getDrawable		 null
Color app:tint setImageTintList
getImageTintList		 ?attr/colorOnSecondary (see all states)

Styles

Element Style
Default style Widget.MaterialComponents.FloatingActionButton

Default style theme attribute: ?attr/floatingActionButtonStyle

See the full list of styles and attrs.

Extended FABs

The extended FAB is wider, and it includes a text label.

Note: ExtendedFloatingActionButton is a child class of MaterialButton, rather than FloatingActionButton. This means that several attributes which are applicable to FloatingActionButton have different naming in ExtendedFloatingActionButton. For example, FloatingActionButton uses app:srcCompat to set the icon drawable, whereas ExtendedFloatingActionButton uses app:icon. See the attributes tables below for more details.

API and source code:

Extended FAB example

The following example shows an extended FAB with a plus icon.

Teal FAB with plus icon and "Extended" label

In the layout:

<androidx.coordinatorlayout.widget.CoordinatorLayout
    ...
    >

  <!-- Main content -->

  <com.google.android.material.floatingactionbutton.ExtendedFloatingActionButton
    android:id="@+id/extended_fab"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_margin="16dp"
    android:layout_gravity="bottom|right"
    android:contentDescription="@string/extended_fab_content_desc"
    android:text="@string/extended_fab_label"
    app:icon="@drawable/ic_plus_24px"/>

</androidx.coordinatorlayout.widget.CoordinatorLayout>

In code:

extendedFab.setOnClickListener {
    // Respond to Extended FAB click
}

Anatomy and key properties

Extended FAB anatomy diagram

An extended FAB has a text label, a transparent container and an optional icon.

  1. Container
  2. Icon (Optional)
  3. Text label

Container attributes

Element Attribute Related method(s) Default value
Color app:backgroundTint setBackgroundTintList
getBackgroundTintList		 ?attr/colorSecondary (see all states)
Stroke color app:strokeColor setStrokeColor
getStrokeColor		 null
Stroke width app:strokeWidth setStrokeWidth
getStrokeWidth		 0dp
Size app:collapsedSize N/A
Shape app:shapeAppearance
app:shapeAppearanceOverlay		 setShapeAppearanceModel
getShapeAppearanceModel		 ?attr/shapeAppearanceSmallComponent
Elevation app:elevation setElevation
getElevation		 6dp
Hovered/Focused elevation app:hoveredFocusedTranslationZ N/A 2dp
Pressed elevation app:pressedTranslationZ N/A 6dp
Ripple app:rippleColor variations of ?attr/colorOnSecondary, see all states
Motion app:showMotionSpec
app:hideMotionSpec
extendMotionSpec
shrinkMotionSpec		 set*MotionSpec
set*MotionSpecResource
get*MotionSpec		 see animators

Icon attributes

Element Attribute Related method(s) Default value
Icon app:icon setIcon
setIconResource
getIcon		 null
Color app:iconTint setIconTint
setIconTintResource
getIconTint		 ?attr/colorOnSecondary (see all states)
Size app:iconSize setIconSize
getIconSize		 24dp
Padding between icon and text app:iconPadding setIconPadding
getIconPadding		 16dp

Text label

Element Attribute Related method(s) Default value
Text label android:text setText
getText		 null
Color android:textColor setTextColor
getTextColor		 ?attr/colorOnSecondary (see all states)
Typography android:textAppearance setTextAppearance ?attr/textAppearanceButton

Styles

Element Style
Default style Widget.MaterialComponents.ExtendedFloatingActionButton.Icon
Text-only when
extended style		 Widget.MaterialComponents.ExtendedFloatingActionButton

Default style theme attribute: ?attr/extendedFloatingActionButtonStyle

See the full list of styles and attrs.

Theming FABs

FAB theming example

API and source code:

The following example shows a regular, mini, and extended FABs with Material Theming.

"3 square pink FABs with cut corners with brown plus icons: 56dp, 40dp, 56dp with "Extended" label"

Implementing FAB theming

Using theme attributes and styles in res/values/styles.xml (themes all FABs and affects other components):

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="colorSecondary">@color/shrine_pink_100</item>
    <item name="colorOnSecondary">@color/shrine_pink_900</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="shapeAppearanceSmallComponent">@style/ShapeAppearance.App.SmallComponent</item>
</style>

<style name="ShapeAppearance.App.SmallComponent" parent="ShapeAppearance.MaterialComponents.SmallComponent">
    <item name="cornerFamily">cut</item>
    <item name="cornerSize">4dp</item>
</style>

Or using a default style theme attribute, styles and a theme overlay (themes all FABs but does not affect other components):

<style name="Theme.App" parent="Theme.MaterialComponents.*">
    ...
    <item name="extendedFloatingActionButtonStyle">@style/Widget.App.ExtendedFloatingActionButton</item>
    <item name="floatingActionButtonStyle">@style/Widget.App.FloatingActionButton</item>
</style>

<style name="Widget.App.ExtendedFloatingActionButton" parent="Widget.MaterialComponents.ExtendedFloatingActionButton.Icon">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.FloatingActionButton</item>
    <item name="shapeAppearanceOverlay">
      @style/ShapeAppearance.App.SmallComponent
    </item>
</style>

<style name="Widget.App.FloatingActionButton" parent="Widget.MaterialComponents.FloatingActionButton">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.FloatingActionButton</item>
    <item name="shapeAppearanceOverlay">
      @style/ShapeAppearance.App.SmallComponent
    </item>
</style>

<style name="ThemeOverlay.App.FloatingActionButton" parent="">
    <item name="colorSecondary">@color/shrine_pink_100</item>
    <item name="colorOnSecondary">@color/shrine_pink_900</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
  </style>

or using one of the styles in the layout (affects only this FAB):

<com.google.android.material.floatingactionbutton.FloatingActionButton
    ...
    style="@style/Widget.App.FloatingActionButton"
/>