Material Design

Buttons

Open bugs badge

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.

An animation showing a Material Design text button. An animation showing a Material Design outlined button. An animation showing a Material Design contained button. An animation showing a Material Design floating action button.

Design & API documentation

Table of contents


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:

An animation showing a Material Design text button.

Swift

button.applyTextTheme(withScheme: containerScheme)

Objective-C

[self.button applyTextThemeWithScheme:self.containerScheme];

Material outlined button theming:

An animation showing a Material Design outlined button.

Swift

button.applyOutlinedTheme(withScheme: containerScheme)

Objective-C

[self.button applyOutlinedThemeWithScheme:self.containerScheme];

Material contained button theming:

An animation showing a Material Design contained button.

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:

An animation showing a Material Design floating action button.

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](https://github.com/material-components/material-components-ios/tree/stable/components/Buttons/docs/theming.md) 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: ```bash 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 An animation showing a Material Design text button. 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 An animation showing a Material Design outlined button. 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 An animation showing a Material Design contained button. 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 An animation showing a Material Design floating action button. 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](https://github.com/material-components/material-components-ios/tree/stable/components/Buttons/docs/theming.md) 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: ```bash 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](https://github.com/material-components/material-components-ios/tree/stable/components/Buttons/docs/theming.md) 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: ```bash 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](https://github.com/material-components/material-components-ios/tree/stable/components/Buttons/docs/theming.md) 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: ```bash 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];