nkey / material-components-ios

Buttons

Material design buttons allow users to take actions, and make choices, with a single tap. There are many distinct button styles including text buttons, contained buttons, and floating action buttons.

Design & API documentation

• Material Design guidelines: Buttons
• Class: MDCRaisedButton
• Class: MDCButton
• Class: MDCFlatButton
• Class: MDCFloatingButton
• Enumeration: Enumerations
• Enumeration: MDCFloatingButtonImageLocation
• Enumeration: MDCFloatingButtonMode
• Enumeration: MDCFloatingButtonShape

Table of contents

• Overview
• Installation
  • Installation with CocoaPods
  • Importing
• Usage
  • Typical use
  • Typical use: floating action buttons
  • Customizing elevation
  • Customizing floating action buttons
  • Interface Builder
• Extensions
  • Theming
  • How to theme an MDCButton
  • How to theme an MDCFloatingButton
• Accessibility
  • Set -accessibilityLabel
  • Minimum touch size
• Unsupported
  • How to theme a button using a themer
  • Color Theming
  • Typography Theming
  • Shape Theming

---

Overview

MDCButton is a highly-configurable UIButton implementation that provides support for shadow elevation, Material Design ripples, and other stateful design APIs.

Installation

Installation with CocoaPods

Add the following to your Podfile:

pod 'MaterialComponents/Buttons'

Then, run the following command:

pod install

Importing

To import the component:

Swift

import MaterialComponents.MaterialButtons

Objective-C

#import "MaterialButtons.h"

Usage

Typical use

MDCButton is a subclass of UIButton, but with more options for customizing the button's style and behavior. To initialize an MDCButton, you must alloc/init an instance directly instead of using buttonWithType:, which has been marked unavailable.

Swift

let button = MDCButton()

Objective-C

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

See the MDCButton API docs for a complete list of features that MDCButton provides in addition to UIButton's features.

Typical use: floating action buttons

MDCFloatingButton is a subclass of MDCButton that implements the Material Design floating action button style and behavior. Floating action buttons should be provided with a templated image for their normal state and then themed accordingly.

Swift

// Note: you'll need to provide your own image - the following is just an example.
let plusImage = UIImage(named: "plus").withRenderingMode(.alwaysTemplate)
let button = MDCFloatingButton()
button.setImage(plusImage, forState: .normal)

Objective-C

// Note: you'll need to provide your own image - the following is just an example.
UIImage *plusImage =
    [[UIImage imageNamed:@"plus"] imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate];
MDCFloatingButton *button = [[MDCFloatingButton alloc] init];
[button setImage:plusImage forState:UIControlStateNormal];

Customizing elevation

The elevation of a button can be changed for a given control state using setElevation:forState:.

See the Material Design shadow guidelines for a detailed overview of different shadow elevations.

For example, to make a button elevate on tap like a floating action button:

Swift

button.setElevation(6, for: .normal)
button.setElevation(12, for: .highlighted)

Objective-C

[button setElevation:6 forState:UIControlStateNormal];
[button setElevation:12 forState:UIControlStateNormal];

Customizing floating action buttons

A floating action button can be configured with a combination of shape and mode. The .default shape is a 56-point circle containing a single image or short title. The .mini shape is a smaller, 40-point circle. The .normal mode is a circle containing an image or short title. The .expanded mode is a "pill shape" and should include both an image and a single-word title. The .expanded mode should only be used in the largest layouts. For example, an iPad in full screen.

While in the .expanded mode, a floating button can position its imageView to either the leading or trailing side of the title by setting the imageLocation property.

Because of the combination of shapes and modes available to the floating action button, some UIButton property setters have been made unavailable and replaced with methods to set them for a specific mode and shape combination. Getters for these values are not available, and the normal getter will return the current value of the property.

• -setContentEdgeInsets is replaced with -setContentEdgeInsets:forShape:inMode:
• -setHitAreaInsets is replaced with -setHitAreaInsets:forShape:inMode:
• -setMinimumSize is replaced with -setMinimumSize:forShape:inMode:
• -setMaximumSize is replaced with -setMaximumSize:forShape:inMode:

Interface Builder

MDCButton and its subclasses can be used in Interface Builder, but the button type must be set to "custom" in order for the button's highlight states to work as expected.

Extensions

Theming

You can theme an MDCButton to match a Material Design button style using theming extensions. Learn more about theming extensions.

How to theme an MDCButton

First, import both Buttons and Buttons Theming and create an instance of MDCButton.

Swift

import MaterialComponents.MaterialButtons
import MaterialComponents.MaterialButtons_Theming

let button = MDCButton()

Objective-C

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

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

You can then provide a container scheme instance to any of the MDCButton theming extensions. Learn more about container schemes.

Material text button theming:

Swift

button.applyTextTheme(withScheme: containerScheme)

Objective-C

[self.button applyTextThemeWithScheme:self.containerScheme];

Material outlined button theming:

Swift

button.applyOutlinedTheme(withScheme: containerScheme)

Objective-C

[self.button applyOutlinedThemeWithScheme:self.containerScheme];

Material contained button theming:

Swift

button.applyContainedTheme(withScheme: containerScheme)

Objective-C

[self.button applyContainedThemeWithScheme:self.containerScheme];

How to theme an MDCFloatingButton

First, create a button and import the theming extension header for Buttons.

Swift

import MaterialComponents.MaterialButtons
import MaterialComponentsBeta.MaterialButtons_Theming

let floatingButton = MDCFloatingButton()

Objective-C

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

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

Material floating action button theming:

Swift

floatingButton.applySecondaryTheme(withScheme: containerScheme)

Objective-C

[self.floatingButton applySecondaryThemeWithScheme: self.containerScheme];

Accessibility

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.

Objective-C

button.accessibilityLabel = @"Create";

Swift

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.

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

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

Set the minimum visual size of the button

Set your buttons to have a minimum size. Material Buttons guidelines typically recommend a minimum height of 36 points and a minimum width of 64 points.

Objective-C

button.minimumSize = CGSizeMake(64, 36);

Swift

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

Exceptions

However there are some clear exceptions for these rules. Please adjust your buttons sizes accordingly.

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

Unsupported

How to theme a button using a themer

Note: This documentation refers to legacy APIs that will eventually be deprecated. Please consider reading the updated theming documentation instead.

You can theme an MDCButton to match one of the Material Design button styles using your app's schemes in the ButtonThemer extension.

You must first add the ButtonThemer extension to your project:

pod 'MaterialComponents/Buttons+ButtonThemer'

You can then import the extension and create an MDCButtonScheme instance. A button scheme defines the design parameters that you can use to theme your buttons.

Swift

// Step 1: Import the ButtonThemer extension
import MaterialComponents.MaterialButtons_ButtonThemer

// Step 2: Create or get a button scheme
let buttonScheme = MDCButtonScheme()

// Step 3: Apply the button scheme to your component using the desired button style

Objective-C

// Step 1: Import the ButtonThemer extension
#import "MaterialButtons+ButtonThemer.h"

// Step 2: Create or get a button scheme
MDCButtonScheme *buttonScheme = [[MDCButtonScheme alloc] init];

// Step 3: Apply the button scheme to your component using the desired button style

Text buttons



To theme a button as a Material Design text button, use MDCTextButtonThemer.

Swift

MDCTextButtonThemer.applyScheme(buttonScheme, to: button)

Objective-C

[MDCTextButtonThemer applyScheme:buttonScheme toButton:button];

Outlined buttons



To theme a button as a Material Design outlined button, use MDCOutlinedButtonThemer with an MDCButton.

Swift

MDCOutlinedButtonThemer.applyScheme(buttonScheme, to: button)

Objective-C

[MDCOutlinedButtonThemer applyScheme:buttonScheme toButton:button];

Contained buttons



To theme a button as a Material Design contained button, use MDCContainedButtonThemer.

Swift

MDCContainedButtonThemer.applyScheme(buttonScheme, to: button)

Objective-C

[MDCContainedButtonThemer applyScheme:buttonScheme toButton:button];

Floating action buttons



To theme a button as a Material Design floating action button, use MDCFloatingActionButtonThemer with an MDCFloatingButton.

Swift

MDCFloatingActionButtonThemer.applyScheme(buttonScheme, to: button)

Objective-C

[MDCFloatingActionButtonThemer applyScheme:buttonScheme toButton:button];

Color Theming

Note: This documentation refers to legacy APIs that will eventually be deprecated. Please consider reading the updated theming documentation instead.

You can theme buttons with your app's color scheme using the ColorThemer extension.

You must first add the Color Themer extension to your project:

pod 'MaterialComponents/Buttons+ColorThemer'

Swift

// Step 1: Import the ColorThemer extension
import MaterialComponents.MaterialButtons_ColorThemer

// Step 2: Create or get a color scheme
let colorScheme = MDCSemanticColorScheme()

// Step 3: Apply the color scheme to your component using the desired button style
MDCContainedButtonColorThemer.applySemanticColorScheme(colorScheme, to: component)
MDCFloatingButtonColorThemer.applySemanticColorScheme(colorScheme, to: component)
MDCTextButtonColorThemer.applySemanticColorScheme(colorScheme, to: component)

Objective-C

// Step 1: Import the ColorThemer extension
#import "MaterialButtons+ColorThemer.h"

// Step 2: Create or get a color scheme
id<MDCColorScheming> colorScheme = [[MDCSemanticColorScheme alloc] initWithDefaults:MDCColorSchemeDefaultsMaterial201804];

// Step 3: Apply the color scheme to your component using the desired button style
[MDCContainedButtonColorThemer applySemanticColorScheme:colorScheme
     toButton:component];
[MDCFloatingButtonColorThemer applySemanticColorScheme:colorScheme
     toButton:component];
[MDCTextButtonColorThemer applySemanticColorScheme:colorScheme
     toButton:component];

Typography Theming

Note: This documentation refers to legacy APIs that will eventually be deprecated. Please consider reading the updated theming documentation instead.

You can theme buttons with your app's typography scheme using the TypographyThemer extension.

You must first add the Typography Themer extension to your project:

pod 'MaterialComponents/Buttons+TypographyThemer'

Swift

// Step 1: Import the TypographyThemer extension
import MaterialComponents.MaterialButtons_TypographyThemer

// Step 2: Create or get a typography scheme
let typographyScheme = MDCTypographyScheme()

// Step 3: Apply the typography scheme to your component
MDCButtonTypographyThemer.applyTypographyScheme(typographyScheme, to: component)

Objective-C

// Step 1: Import the TypographyThemer extension
#import "MaterialButtons+TypographyThemer.h"

// Step 2: Create or get a typography scheme
id<MDCTypographyScheming> typographyScheme = [[MDCTypographyScheme alloc] init];

// Step 3: Apply the typography scheme to your component
[MDCButtonTypographyThemer applyTypographyScheme:colorScheme
     toButton:component];

Shape Theming

Note: This documentation refers to legacy APIs that will eventually be deprecated. Please consider reading the updated theming documentation instead.

You can theme buttons with your app's shape scheme using the ShapeThemer extension.

You must first add the ShapeThemer extension to your project:

pod 'MaterialComponents/Buttons+ShapeThemer'

Swift

// Step 1: Import the ShapeThemer extension
import MaterialComponents.MaterialButtons_ShapeThemer

// Step 2: Create or get a shape scheme
let shapeScheme = MDCShapeScheme()

// Step 3: Apply the shape scheme to your component
MDCButtonShapeThemer.applyShapeScheme(shapeScheme, to: component)
MDCFloatingButtonShapeThemer.applyShapeScheme(shapeScheme, to: component)

Objective-C

// Step 1: Import the ShapeThemer extension
#import "MaterialButtons+ShapeThemer.h"

// Step 2: Create or get a shape scheme
id<MDCShapeScheming> shapeScheme = [[MDCShapeScheme alloc] init];

// Step 3: Apply the shape scheme to your component
[MDCButtonShapeThemer applyShapeScheme:shapeScheme
     toButton:component];
[MDCFloatingButtonShapeThemer applyShapeScheme:shapeScheme
     toButton:component];