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

Table of contents

• Overview
• Installation
  • Installation with CocoaPods
  • Importing
• Usage
  • Typical use: themed buttons
  • Typical use: floating action buttons
  • Customizing elevation
  • Customizing floating action buttons
  • Interface Builder
• Extensions
  • Theming
  • Color Theming
  • Typography Theming
  • Shape Theming
• Accessibility
  • Set -accessibilityLabel
  • Minimum touch size

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: themed buttons

Create an instance of MDCButton and theme it with as one of the Material Design button styles using the ButtonThemer extension. Once themed, use the button like you would use a typical UIButton instance.

Swift

let button = MDCButton()

// Themed as a text button:
MDCTextButtonThemer.applyScheme(buttonScheme, to: button)

Objective-C

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

// Themed as a text button:
[MDCTextButtonThemer applyScheme:buttonScheme toButton:button];

See the ButtonThemer documentation for a full list of supported Material Design button styles.

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.

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)
MDCFloatingActionButtonThemer.applyScheme(buttonScheme, to: button)

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];
[MDCFloatingActionButtonThemer applyScheme:buttonScheme toButton:button];

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

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

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

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

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: