material-components_material-components-ios/components/Buttons/docs/fabs.md

Buttons: floating action buttons

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

Contents

• Using FABs
• Regular FAB
• Mini FAB
• Extended FAB
• Theming

---

Using FABs

Installing

Because MDCFloatingButton is a subclass of MDCButton, the steps for installing it are the same.

In order to use MDCFloatingButton, first add the Buttons subspec to your Podfile:

pod MaterialComponents/Buttons

Then, run the installer:

pod install

After that, import the relevant target or file and initialize an MDCFloatingButton.

Swift

import MaterialComponents.MaterialButtons

let fab = MDCFloatingButton()

Objective-C

#import "MaterialButtons.h"

MDCFloatingButton *fab = [[MDCFloatingButton alloc] init];

Making FABs accessible

To help make your FABs usable to as many users as possible, apply the following:

• Set an appropriate accessibilityLabel value if your button does not have a title or only has an icon:

Swift

floatingButton.accessibilityLabel = "Create"

Objective-C

floatingButton.accessibilityLabel = @"Create";

• Set the minimum visual height to 36 and miniumum visual width to 64

Swift

floatingButton.minimumSize = CGSize(width: 64, height: 48)

Objective-C

floatingButton.minimumSize = CGSizeMake(64, 36);

• Set the touch areas to at least 44 points high and 44 wide. To minimize FAB's visual size while allowing for larger touchable areas, set the hitAreaInsets to a negative value. Maintain sufficient distance between the FAB touch targets. For more see the Touch and click targets in the spec.

Swift

let buttonVerticalInset =
min(0, -(kMinimumAccessibleButtonSize.height - button.bounds.height) / 2);
let buttonHorizontalInset =
min(0, -(kMinimumAccessibleButtonSize.width - button.bounds.width) / 2);
floatingButton.hitAreaInsets =
UIEdgeInsetsMake(buttonVerticalInset, buttonHorizontalInset,
buttonVerticalInset, buttonHorizontalInset);

Objective-C

CGFloat verticalInset = MIN(0, -(48 - CGRectGetHeight(fab.bounds)) / 2);
CGFloat horizontalInset = MIN(0, -(48 - CGRectGetWidth(fab.bounds)) / 2);
floatingButton.hitAreaInsets = UIEdgeInsetsMake(verticalInset, horizontalInset, verticalInset, horizontalInset);

Note There are some clear exceptions for these rules. Please adjust your buttons sizes accordingly.

• Optional Set an appropriate accessibilityHint

Apple rarely recommends using the accessibilityHint because the label should already be clear enough to indicate what will happen. Before you consider setting an -accessibilityHint consider if you need it or if the rest of your UI could be adjusted to make it more contextually clear.

A well-crafted, thoughtful user interface can remove the need for accessibilityHint in most situations. Examples for a selection dialog to choose one or more days of the week for a repeating calendar event:

• (Good) The dialog includes a header above the list of days reading, "Event repeats weekly on the following day(s)." The list items do not need accessibilityHint values.
• (Bad) The dialog has no header above the list of days. Each list item (representing a day of the week) has the accessibilityHint value, "Toggles this day."

Types

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

All three types of FABs are implemented by MDCFloatingButton, a subclass of MDCButton.

• GitHub source

Regular FAB

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

Regular FAB example

To create a regular FAB use the +floatingButtonWithShape: constructor with a value of MDCFloatingButtonShapeDefault and make sure the mode property is set to MDCFloatingButtonModeNormal.

For more information on theming FABs see the Theming section.

Swift

let fab = MDCFloatingButton(shape: `default`)

Objective-C

MDCFloatingButton *fab =
    [MDCFloatingButton floatingButtonWithShape:MDCFloatingButtonShapeDefault];

Anatomy and key properties

A regular FAB has a container and an icon.

1. Container
2. Icon

Container attributes

	Attribute	Related method(s)	Default value
Color	backgroundColor	setBackgroundColor:forState: backgroundColorForState	blue 500 from this Theming doc.
Stroke color		setBorderColor:forState: borderColorForState:	nil
Stroke width		setBorderWidth:forState: borderWidthForState:	0
Ripple color	inkColor	setInkColor inkColor	White at 20% opacity

Icon attributes

	Attribute	Related method(s)	Default value
Icon	imageView	setImage:forState: imageForState:	nil
Color	imageView.tintColor	setImageViewTintColor:forState: imageViewTintColorForState:	nil

Mini FAB

A mini FAB should be used on smaller screens.

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

Mini FAB example

To create a mini FAB use the +floatingButtonWithShape: constructor with a value of MDCFloatingButtonShapeMini and make sure the mode property is set to MDCFloatingButtonModeNormal.

For more information on theming FABs see the Theming section.

Swift

let fab = MDCFloatingButton(shape: mini)

Objective-C

MDCFloatingButton *fab =
    [MDCFloatingButton floatingButtonWithShape:MDCFloatingButtonShapeMini];

Anatomy and key properties

A mini FAB has a container and an icon.

1. Container
2. Icon

Container attributes

	Attribute	Related method(s)	Default value
Color	backgroundColor	setBackgroundColor:forState: backgroundColorForState	blue 500 from this Theming doc.
Stroke color		setBorderColor:forState: borderColorForState:	nil
Stroke width		setBorderWidth:forState: borderWidthForState:	0
Ripple color	inkColor	setInkColor inkColor	White at 20% opacity

Icon attributes

	Attribute	Related method(s)	Default value
Icon	imageView	setImage:forState: imageForState:	nil
Color	imageView.tintColor	setImageViewTintColor:forState: imageViewTintColorForState:	nil

Extended FAB

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

Extended FAB example

To create an extended FAB use the +floatingButtonWithShape: constructor with a value of MDCFloatingButtonShapeDefault and make sure the mode property is set to MDCFloatingButtonModeExpanded.

For more information on theming FABs see the Theming section.

Swift

let fab = MDCFloatingButton(shape: .default)
fab.mode = .expanded

Objective-C

MDCFloatingButton *fab =
    [MDCFloatingButton floatingButtonWithShape:MDCFloatingButtonShapeDefault];
fab.mode = MDCFloatingButtonModeExpanded;

Anatomy and key properties

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

1. Container
2. Icon
3. Text label

Container attributes

	Attribute	Related method(s)	Default value
Color	backgroundColor	setBackgroundColor:forState: backgroundColorForState	blue 500 from this Theming doc.
Stroke color		setBorderColor:forState: borderColorForState:	nil
Stroke width		setBorderWidth:forState: borderWidthForState:	0
Ripple color	inkColor	setInkColor inkColor	White at 20% opacity

Icon attributes

	Attribute	Related method(s)	Default value
Icon	imageView	setImage:forState: imageForState:	nil
Color	imageView.tintColor	setImageViewTintColor:forState: imageViewTintColorForState:	nil

Text label attributes

	Attribute	Related method(s)	Default value
Text label	titleLabel	setTitle:forState: titleForState:	nil
Color	titleLabel.textColor	setTitleColor:forState: titleColorForState:	UIColor.blackColor
Typography	titleLabel.font	setFont: and font on titleLabel	Button

Theming

You can theme an MDCFloatingButton to have a secondary theme using the MDCFloatingButton theming extension. Learn more about theming extensions and container schemes. Below is a screenshot of Material FABs with the Material Design Shrine theme:

To make use of the theming methods shown in the examples above install the Buttons theming extensions with Cocoapods. First, add the following line to your Podfile:

pod MaterialComponents/Buttons+Theming

Then run the installer:

pod install

Next, import the Buttons theming target.

Swift

import MaterialComponents.MaterialButtons
import MaterialComponents.MaterialButtons_Theming

Objective-C

#import "MaterialButtons.h"
#import <MaterialComponents/MaterialButtons+Theming.h>

From there, pass a container scheme into the theming method on an MDCFloatingButton instance.

Swift

let fab = MDCFloatingButton(shape: `default`)
fab.applySecondaryThemeWith(withScheme:containerScheme)

Objective-C

MDCFloatingButton *fab =
    [MDCFloatingButton floatingButtonWithShape:MDCFloatingButtonShapeMini];
[fab applySecondaryThemeWithScheme:self.containerScheme];