Material Design

Dialogs

Open bugs badge

Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

Dialogs

Design & API documentation

Table of contents


Overview

To display a modal using MaterialDialogs you set two properties on the view controller to be presented. Set modalPresentationStyle to UIModalPresentationCustom and set transitioningDelegate to and instance of MDCDialogTransitionController. Then you present the view controller from the root controller to display it as a modal dialog.

Presentation and transition controller

Presenting dialogs uses two classes: MDCDialogPresentationController and MDCDialogTransitionController. These allow the presentation of view controllers in a material specificed manner. MDCDialogPresentationController is a subclass of UIPresentationController that observes the presented view controller for preferred content size. MDCDialogTransitionController implements UIViewControllerAnimatedTransitioning and UIViewControllerTransitioningDelegate to vend the presentation controller during the transition.

Alert controller

MDCAlertController provides a simple interface for developers to present a modal dialog according to the Material spec.

Installation

Installation with CocoaPods

Add the following to your Podfile:

pod 'MaterialComponents/Dialogs'

Then, run the following command:

pod install

Importing

To import the component:

Swift

import MaterialComponents.MaterialDialogs

Objective-C

#import "MaterialDialogs.h"

Usage

Typical use: modal dialog

Swift

// The following is called from the presenting view controller and has the
// following variable defined to keep a reference to the transition
// controller.
strong var dialogTransitionController: MDCDialogTransitionController

// To present the dialog myDialogViewController
dialogTransitionController = MDCDialogTransitionController()
myDialogViewController.modalPresentationStyle = .custom
myDialogViewController.transitioningDelegate = dialogTransitionController

present(myDialogViewController, animated: true, completion:...)

Objective-C

// self is the presenting view controller and which has the following property
// defined to keep a reference to the transition controller.
@property(nonatomic) MDCDialogTransitionController *dialogTransitionController;

// To present the dialog myDialogViewController
self.dialogTransitionController = [[MDCDialogTransitionController alloc] init];
myDialogViewController.modalPresentationStyle = UIModalPresentationCustom;
myDialogViewController.transitioningDelegate = self.dialogTransitionController;
[self presentViewController:myDialogViewController animated:YES completion:...];

Typical use: alert

Swift

// Present a modal alert
let alertController = MDCAlertController(title: titleString, message: messageString)
let action = MDCAlertAction(title:"OK") { (action) in print("OK") }
alertController.addAction(action)

present(alertController, animated:true, completion:...)

Objective-C

// Present a modal alert
MDCAlertController *alertController =
[MDCAlertController alertControllerWithTitle:titleString
                                     message:messageString];

MDCAlertAction *alertAction =
    [MDCAlertAction actionWithTitle:@"OK"
                            handler:^(MDCAlertAction *action) {
       NSLog(@"OK");
    }];

[alertController addAction:alertAction];

[self presentViewController:alertController animated:YES completion:...];

Extensions

Color Theming

You can theme a dialog with your app’s color scheme using the ColorThemer extension.

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

pod 'MaterialComponents/Dialogs+ColorThemer'

Swift

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

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

// Step 3: Apply the color scheme to your component
MDCAlertColorThemer.applySemanticColorScheme(colorScheme, to: component)

Objective-C

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

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

// Step 3: Apply the color scheme to your component
[MDCAlertColorThemer applySemanticColorScheme:colorScheme
     toAlertController:component];

Typography Theming

You can theme a dialog with your app’s typography scheme using the TypographyThemer extension.

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

pod 'MaterialComponents/Dialogs+TypographyThemer'

Swift

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

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

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

Objective-C

// Step 1: Import the TypographyThemer extension
#import "MaterialDialogs+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
[MDCAlertTypographyThemer applyTypographyScheme:colorScheme
     toAlertController:component];

Accessibility

MDCPresentationController Accessibility

As MDCPresentationController is responsible for the presentation of your custom view controllers, it does not implement any accessibility functionality itself.

-accessibilityPerformEscape Behavior

If you intend your presented view controller to dismiss when a user in VoiceOver mode has performed the escape gesture the view controller should implement the accessibilityPerformEscape method.

- (BOOL)accessibilityPerformEscape {
  [self.presentingViewController dismissViewControllerAnimated:YES completion:NULL];
  return YES;
}