Skip to content

Latest commit

 

History

History
385 lines (275 loc) · 14.5 KB

buttons.md

File metadata and controls

385 lines (275 loc) · 14.5 KB

Buttons

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

"Button on a screen"

Contents

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)"

Example of the four button types

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

Text button

An animated Material Design 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.

Text button anatomy diagram

  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

An animated Material Design 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.

Outlined button anatomy diagram

  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

An animated Material Design 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.

Contained button anatomy diagram

  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:

Shrine buttons

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.