Action Sheet

Material design action sheets should be used as an overflow menu. An Action Sheet comes up from the bottom of the screen and displays actions a user can take.

Design & API documentation

Table of contents

• Overview
• Installation
  • Installation with CocoaPods
  • Importing
• Usage
  • Typical use
• MDCActionSheetController vs. UIAlertControllerStyleActionSheet
• Customization
  • Positioning Action Sheet Actions
• Extensions
  • Theming
• Accessibility
  • Set -isScrimAccessibilityElement
  • Set -scrimAccessibilityLabel
  • Set -scrimAccessibilityHint
  • Set -scrimAccessibilityTraits

Overview

MDCActionSheetController is a material design implementation of UIAlertControllerStyleActionSheet.

Installation

Installation with CocoaPods

Add the following to your Podfile:

pod 'MaterialComponents/ActionSheet'

Then, run the following command:

pod install

Importing

To import the component:

Swift

import MaterialComponents.MaterialActionSheet

Objective-C

#import "MaterialActionSheet.h"

Usage

Typical use

Create an instance of MDCActionSheetController and add actions to it. You can now present the action sheet controller.

Swift

let actionSheet = MDCActionSheetController(title: "Action Sheet", 
                                           message: "Secondary line text")
let actionOne = MDCActionSheetAction(title: "Home", 
                                     image: UIImage(named: "Home"), 
                                     handler: { print("Home action" })
let actionTwo = MDCActionSheetAction(title: "Email", 
                                     image: UIImage(named: "Email"), 
                                     handler: { print("Email action" })
actionSheet.addAction(actionOne)
actionSheet.addAction(actionTwo)

present(actionSheet, animated: true, completion: nil)

Objective-C

MDCActionSheetController *actionSheet =
    [MDCActionSheetController actionSheetControllerWithTitle:@"Action sheet"
                                                     message:@"Secondary line text"];
MDCActionSheetAction *homeAction = 
    [MDCActionSheetAction actionWithTitle:@"Home"
                                    image:[UIImage imageNamed:@"ic_home"]
                                  handler:nil];
MDCActionSheetAction *favoriteAction =
    [MDCActionSheetAction actionWithTitle:@"Favorite"
                                    image:[UIImage imageNamed:@"ic_favorite"]
                                  handler:nil];
[actionSheet addAction:homeAction];
[actionSheet addAction:favoriteAction];
[self presentViewController:actionSheet animated:YES completion:nil];

MDCActionSheetController vs. UIAlertControllerStyleActionSheet

MDCActionSheetController is intended to mirror a UIAlertController with the UIAlertControllerStyleActionSheet style.

Similarities

1. Both classes are presented from the bottom of the screen on an iPhone and have a list of actions.

2. Both classes support optional title and message properties.

Differences

1. UIAlertControllerActionSheetStyle requires that you set the popoverPresentationController on larger devices, MDCActionSheetController doesn't support popoverPresentationController but instead always comes up from the bottom of the screen.

2. UIAlertControllerStyleActionSheet is a style of UIAlertController and not its own class. If you need a Material UIAlertController please see the MDCAlertController class.

3. MDCActionSheetController does not support text fields.

4. MDCActionSheetController does not have a preferredAction.

Customization

Positioning Action Sheet Actions

The layout of the Action Sheet list items can be adjusted with the contentEdgeInsets API. Positive values will inset the content and negative values will outset the conent. The insets apply to all action items.

For example, setting top and bottom insets (positive values) will reduce the height of the Action list items.

Setting a left outset (negative value) and right inset (positive value) will shift the Action's content to the trailing edge.

Extensions

Theming

You can theme an MDCActionSheet to match the Material Design style by using a theming extension. The content below assumes you have read the article on Theming.

First, create an action sheet and import the theming extension header for Action Sheets.

Swift

import MaterialComponents.MaterialActionSheet
import MaterialComponents.MaterialActionSheet_Theming

let actionSheet = MDCActionSheetController()

Objective-C

#import <MaterialComponents/MaterialActionSheet.h>
#import <MaterialComponents/MaterialActionSheet+Theming.h>

MDCActionSheetController *actionSheet = [[MDCActionSheetController alloc] init];

You can then provide a container scheme instance to any of the MDCActionSheet theming extensions.

Then, you can theme your action sheet.

Swift

actionSheet.applyTheme(withScheme: containerScheme)

Objective-C

[self.actionSheet applyThemeWithScheme:self.containerScheme];

Accessibility

To help ensure your Action Sheet is accessible to as many users as possible, please be sure to reivew the following recommendations:

The scrim by default enables the “Z” gesture to dismiss. If isScrimAccessibilityElement is not set or is set to false then scrimAccessibilityLabel, scrimAccessibilityHint, and scrimAccessibilityTraits will have any effect.

Set -isScrimAccessibilityElement

Swift

let actionSheet = MDCActionSheetController()
actionSheet.transitionController.isScrimAccessibilityElement = true

Objective-C

MDCActionSheetController *actionSheet = [MDCActionSheetController alloc] init];
actionSheet.isScrimAccessibilityElement = YES;

Set -scrimAccessibilityLabel

Swift

let actionSheet = MDCActionSheetController()
actionSheet.transitionController.scrimAccessibilityLabel = "Cancel"

Objective-C

MDCActionSheetController *actionSheet = [MDCActionSheetController alloc] init];
actionSheet.scrimAccessibilityLabel = @"Cancel";

Set -scrimAccessibilityHint

Swift

let actionSheet = MDCActionSheetController()
actionSheet.transitionController.scrimAccessibilityHint = "Dismiss the action sheet"

Objective-C

MDCActionSheetController *actionSheet = [MDCActionSheetController alloc] init];
actionSheet.scrimAccessibilityHint = @"Dismiss the action sheet";

Set -scrimAccessibilityTraits

Swift

let actionSheet = MDCActionSheetController()
actionSheet.transitionController.scrimAccessibilityTraits = UIAccessibilityTraitButton

Objective-C

MDCActionSheetController *actionSheet = [MDCActionSheetController alloc] init];
actionSheet.scrimAccessibilityTraits = UIAccessibilityTraitButton;