Dialogs

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

There are four types of dialogs:

1. Alert
2. Simple
3. Confirmation
4. Full-screen

The alert style is the only style supported on iOS. Consider using the ActionSheet component in situations where one of the unsupported dialog types would have been appropriate.

Contents

• Using dialogs
• Making dialogs accessible
• Dialogs examples
• Theming dialogs

Using dialogs

Our dialogs offerings consist of three classes.

• MDCAlertController provides a basic alert interface with support for things like title text, message text, and optional accessory views.
• MDCDialogTransitionController is involved in the presentation of dialogs. It conforms to UIViewControllerAnimatedTransitioning and UIViewControllerTransitioningDelegate, and vends the presentation controllers to be used in presentation and dismissal transitions. It can be used in the presentation of MDCAlertControllers as well as custom dialog view controller classes.
• MDCDialogPresentationController is the UIPresentationController subclass provided by MDCDialogTransitionController.

To present either an MDCAlertController or a custom dialog, set its modalPresentationStyle property to UIModalPresentationCustom and its transitioningDelegate property to an instance of MDCDialogTransitionController. Then, present the view controller from the root controller.

Installing dialogs

In order to install Dialogs with Cocoapods first add the component to your Podfile:

pod MaterialComponents/Dialogs

Then, run the installer.

pod install

After that, import the Dialogs target.

Swift

import MaterialComponents.MaterialDialogs

Objective-C

#import "MaterialDialogs.h"

Making dialogs accessible

MDCPresentationController Accessibility

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

-accessibilityPerformEscape Behavior

Ensure that the accessibility escape gesture in VoiceOver works by implementing the -performAccessibilityEscape method in your custom dialog view controller class.

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

Dialogs examples

Custom dialog example

The sample code below shows how to use the Dialogs component to present a custom dialog. For a more in-depth example, see the DialogsCustomShadowExampleViewController.

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

MDCAlertController example

The sample code below shows how to use the Dialogs component to present an MDCAlertController. For a more in-depth example, see the DialogsTypicalUseExampleViewController.

Swift

// Present a modal alert
let alertController = MDCAlertController(title: "Title string", message: "Message string")
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:@"Title string"
                                     message:@"Message string"];

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

[alertController addAction:alertAction];

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

Anatomy and key properties

The following is an anatomy diagram of a Material dialog:

1. Container
2. Title (optional)
3. Content
4. Buttons (optional)
5. Scrim

Container attributes

Title attributes

Content attributes

Supporting text

Theming dialogs

You can theme a Material Dialog using a container scheme and the Dialogs theming extension. To achieve something like the Shrine theming above first add the Dialogs theming extension to your project by adding the following line to your Podfile:

pod 'MaterialComponents/Dialogs+Theming'

Then import the theming extension and the MDCContainerScheme and create an MDCContainerScheme instance. A container scheme defines the design parameters that you can use to theme your dialogs. Finally, call the appropriate method on the theming extension.

Swift

// Step 1: Import the Dialog theming extension and container scheme
import MaterialComponents.MaterialDialogs_Theming
import MaterialComponents.MaterialContainerScheme

// Step 2: Create or get a container scheme
let containerScheme = MDCContainerScheme()

// Step 3: Apply the container scheme to your component using the desired alert style
alertController.applyTheme(withScheme: containerScheme)

Objective-C

// Step 1: Import the Dialog theming extension and container scheme
#import "MaterialDialogs+Theming.h"
#import "MaterialContainerScheme.h"

// Step 2: Create or get a container scheme
MDCContainerScheme *containerScheme = [[MDCContainerScheme alloc] init];

// Step 3: Apply the container scheme to your component using the desired alert style
[alertController applyThemeWithScheme:containerScheme];

Theming Actions

Actions in MDCAlertController have emphasis which affects how the Dialog's buttons will be themed. High, Medium and Low emphasis are supported.

Swift

  // Create or reuse a Container scheme
  let scheme = MDCContainerScheme()

  // Create an Alert dialog
  let alert = MDCAlertController(title: "Button Theming", message: "Add item to cart?")

  // Add actions with emphases that will generate buttons with the desired appearance. 
  // An example of a high and a medium emphasis actions:
  alert.addAction(MDCAlertAction(title:"Add Item", emphasis: .high, handler: handler))
  alert.addAction(MDCAlertAction(title:"Cancel", emphasis: .high, handler: handler))

  // Make sure to apply theming after all actions are added, so they are themed too!
  alert.applyTheme(withScheme: scheme)

  // Present the alert
  present(alertController, animated:true, completion:nil)

Objective-C

  // Create or reuse a Container scheme
  MDCContainerScheme *scheme = [[MDCContainerScheme alloc] init];

  // Create an Alert dialog
  MDCAlertController *alert = 
      [MDCAlertController alertControllerWithTitle:@"Button Theming" message:@"Add item to cart?"];

  // Add actions with different emphasis, creating buttons with different themes.
  MDCAlertAction *primaryAction = [MDCAlertAction actionWithTitle:@"Add Item"
                                                          emphasis:MDCActionEmphasisHigh
                                                           handler:handler];
  [alert addAction:primaryAction];

  MDCAlertAction *cancelAction = [MDCAlertAction actionWithTitle:@"Cancel"
                                                         emphasis:MDCActionEmphasisMedium
                                                          handler:handler];
  [alert addAction:cancelAction];

  // Make sure to apply theming after all actions are added, so they are themed too!
  [alert applyThemeWithScheme:scheme];

  // Present the alert
  [self presentViewController:alert animated:YES completion:...];