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.
- Material Design guidelines: Buttons
- Class: MDCRaisedButton
- Class: MDCButton
- Class: MDCFlatButton
- Class: MDCFloatingButton
- Enumeration: Enumerations
- Enumeration: MDCFloatingButtonImageLocation
- Enumeration: MDCFloatingButtonMode
- Enumeration: MDCFloatingButtonShape
MDCButton
is a highly-configurable UIButton implementation that provides support for shadow
elevation, Material Design ripples, and other stateful design APIs.
Add the following to your Podfile
:
pod 'MaterialComponents/Buttons'
Then, run the following command:
pod install
To import the component:
import MaterialComponents.MaterialButtons
#import "MaterialButtons.h"
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.
let button = MDCButton()
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.
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.
// 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)
// 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];
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:
button.setElevation(6, for: .normal)
button.setElevation(12, for: .highlighted)
[button setElevation:6 forState:UIControlStateNormal];
[button setElevation:12 forState:UIControlStateNormal];
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:
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.
You can theme an MDCButton to match a Material Design button style using theming extensions. Learn more about theming extensions.
First, import both Buttons and Buttons Theming and create an instance of MDCButton.
import MaterialComponents.MaterialButtons
import MaterialComponents.MaterialButtons_Theming
let button = MDCButton()
#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:
button.applyTextTheme(withScheme: containerScheme)
[self.button applyTextThemeWithScheme:self.containerScheme];
Material outlined button theming:
button.applyOutlinedTheme(withScheme: containerScheme)
[self.button applyOutlinedThemeWithScheme:self.containerScheme];
Material contained button theming:
button.applyContainedTheme(withScheme: containerScheme)
[self.button applyContainedThemeWithScheme:self.containerScheme];
First, create a button and import the theming extension header for Buttons.
import MaterialComponents.MaterialButtons
import MaterialComponentsBeta.MaterialButtons_Theming
let floatingButton = MDCFloatingButton()
#import <MaterialComponents/MaterialButtons.h>
#import <MaterialComponentsBeta/MaterialButtons+Theming.h>
MDCFloatingButton *floatingButton = [[MDCFloatingButton alloc] init];
Material floating action button theming:
floatingButton.applySecondaryTheme(withScheme: containerScheme)
[self.floatingButton applySecondaryThemeWithScheme: self.containerScheme];
To help ensure your buttons are accessible to as many users as possible, please be sure to review the following recommendations:
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.
button.accessibilityLabel = @"Create";
button.accessibilityLabel = "Create"
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.
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.
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);
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 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.
button.minimumSize = CGSizeMake(64, 36);
button.minimumSize = CGSize(width: 64, height: 48)
However there are some clear exceptions for these rules. Please adjust your buttons sizes accordingly.
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."
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.
// 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
// 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
![An animation showing a Material Design text button.](docs/assets/text.gif)
To theme a button as a Material Design text button, use MDCTextButtonThemer
.
MDCTextButtonThemer.applyScheme(buttonScheme, to: button)
[MDCTextButtonThemer applyScheme:buttonScheme toButton:button];
![An animation showing a Material Design outlined button.](docs/assets/outlined.gif)
To theme a button as a Material Design outlined button, use MDCOutlinedButtonThemer
with an MDCButton
.
MDCOutlinedButtonThemer.applyScheme(buttonScheme, to: button)
[MDCOutlinedButtonThemer applyScheme:buttonScheme toButton:button];
![An animation showing a Material Design contained button.](docs/assets/contained.gif)
To theme a button as a Material Design contained button, use MDCContainedButtonThemer
.
MDCContainedButtonThemer.applyScheme(buttonScheme, to: button)
[MDCContainedButtonThemer applyScheme:buttonScheme toButton:button];
![An animation showing a Material Design floating action button.](docs/assets/fab.gif)
To theme a button as a Material Design floating action button, use MDCFloatingActionButtonThemer
with an MDCFloatingButton
.
MDCFloatingActionButtonThemer.applyScheme(buttonScheme, to: button)
[MDCFloatingActionButtonThemer applyScheme:buttonScheme toButton:button];
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'
// 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)
// 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];
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'
// 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)
// 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];
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'
// 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)
// 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];