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

Buttons

Buttons allow users to take actions, and make choices, with a single tap.

Contents

• Using buttons
• Text button
• Outlined button
• Contained button
• Theming

---

Using buttons

Installing

In order to use Material buttons, 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 your button.

Swift

import MaterialComponents.MaterialButtons

let button = MDCButton()

Objective-C

#import "MaterialButtons.h"

MDCButton *button = [[MDCButton alloc] init];

Making Buttons accessible

To help ensure your buttons are accessible to as many users as possible, please be sure to review the following recommendations:

Set -accessibilityLabel

Set an appropriate accessibilityLabel value if your button does not have a title. This is often the case with Floating Action Button instances which typically only have an icon.

Swift

button.accessibilityLabel = "Create"

Objective-C

button.accessibilityLabel = @"Create";

Minimum touch size

Make sure that your buttons have a minimum touch area. The Material spec for buttons calls for buttons that have a visual height of 36 and that touch areas should be at least 48 points high and 48 wide.

Set the touch size

To keep a button's visual sizes small with larger touchable areas, set the hitAreaInsets to a negative value. Be careful to maintain sufficient distance between the button touch targets. This will allow your button to have a large enough touch target while maintaining the desired visual appearance. 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);
button.hitAreaInsets =
UIEdgeInsetsMake(buttonVerticalInset, buttonHorizontalInset,
buttonVerticalInset, buttonHorizontalInset);

Objective-C

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

Set the minimum visual size of the button

Set your buttons to have a minimum size. Though there are some exceptions, Material Buttons guidelines typically recommend a minimum height of 36 points and a minimum width of 64 points.

Swift

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

Objective-C

button.minimumSize = CGSizeMake(64, 36);

Using 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 four types of buttons: 1. Text button 2. Outlined button 3. Contained button 4. Toggle button (not supported in iOS)"

All Material buttons are implemented by MDCButton, a subclass of UIButton.

• GitHub source

Text button

Text buttons are typically used for less-pronounced actions, including those located in dialogs and cards. In cards, text buttons help maintain an emphasis on card content.

Text button example

To use a text button use the text button theming method on the MDCButton theming extension. For more information on theming extensions see the Theming section.

Swift

button.applyTextTheme(withScheme: containerScheme)

Objective-C

[self.button applyTextThemeWithScheme:self.containerScheme];

Anatomy and key properties

A text button has a text label, a transparent container and an optional icon.

1. Text label
2. Container
3. Icon

Text label attributes

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

Container attributes

	Attribute	Related method(s)	Default value
Color	backgroundColor	setBackgroundColor:forState: backgroundColorForState	UIColor.clearColor
Stroke color		setBorderColor:forState: borderColorForState:	nil
Stroke width		setBorderWidth:forState: borderWidthForState:	0
Ripple color	inkColor	setInkColor inkColor	Primary color at 12% opacity

Icon attributes

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

Outlined button

Outlined buttons are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app.

Outlined button example

To achieve an outlined button use the outlined button theming method on the MDCButton theming extension. To access the theming extension see the Theming section.

Swift

button.applyOutlinedTheme(withScheme: containerScheme)

Objective-C

[self.button applyOutlinedThemeWithScheme:self.containerScheme];

Anatomy and Key properties

An outlined button has a text label, a container, and an optional icon.

1. Text label
2. Container
3. Icon

Text label attributes

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

Container attributes

	Attribute	Related method(s)	Default value
Color	backgroundColor	setBackgroundColor:forState: backgroundColorForState	UIColor.clearColor
Stroke color		setBorderColor:forState: borderColorForState:	On surface color at 12% opacity
Stroke width		setBorderWidth:forState: borderWidthForState:	1
Ripple color	inkColor	setInkColor inkColor	Primary color at 12% opacity

Icon attributes

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

Contained button

Contained buttons are high-emphasis, distinguished by their use of elevation and fill. They contain actions that are primary to your app.

Contained button example

Contained buttons are implemented by MDCButton. To achieve a contained button use the contained button theming method on the MDCButton theming extension. To access the theming extension see the Theming section.

Swift

button.applyContainedTheme(withScheme: containerScheme)

Objective-C

[self.button applyContainedThemeWithScheme:self.containerScheme];

Anatomy and Key properties

A contained button has a text label, a container, and an optional icon.

1. Text label
2. Container
3. Icon

Text label attributes

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

Container attributes

	Attribute	Related method(s)	Default value
Color	backgroundColor	setBackgroundColor:forState: backgroundColorForState	Primary color
Stroke color		setBorderColor:forState: borderColorForState:	nil
Stroke width		setBorderWidth:forState: borderWidthForState:	nil
Ripple color	inkColor	setInkColor inkColor	On primary color at 12% opacity

Icon attributes

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

Theming

You can theme an MDCButton to match any of the Material Button styles using theming extensions. Learn more about theming extensions. Below is a screenshot of Material Buttons with the Material Design Shrine theme:

Buttons theming example

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 and initialize a button.

Swift

import MaterialComponents.MaterialButtons
import MaterialComponents.MaterialButtons_Theming

let button = MDCButton()

Objective-C

#import "MaterialButtons.h"
#import "MaterialButtons+Theming.h"

MDCButton *button = [[MDCButton alloc] init];

From there, use the theming methods from the examples to achieve your preferred button style.