Dialogs

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

Android Web check Flutter iOS

Interactive demo

This demo lets you preview the dialog component, its variations, and configuration options. Each tab displays a different type of dialog.


Usage

A dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.

Dialogs are purposefully interruptive, so they should be used sparingly.

Principles

Focused

Dialogs focus user attention to ensure their content is addressed.

Direct

Dialogs should be direct in communicating information and dedicated to completing a task.

Helpful

Dialogs should appear in response to a user task or an action, with relevant or contextual information.


When to use

A banner displays a prominent message and related optional actions. Related Article arrow_downward Snackbars provide brief feedback about an operation through a message at the...

Dialogs should be used for:

  • Errors that block an app’s normal operation
  • Critical information that requires a specific user task, decision, or acknowledgement
Component Priority User action
Snackbar Low priority Optional: Snackbars disappear automatically
Banner Prominent, medium priority Optional: Banners remain until dismissed by the user, or if the state that caused the banner is resolved
Dialog Highest priority Required: Dialogs block app usage until the user takes a dialog action or exits the dialog (if available)

Types

Alert dialogs interrupt users with urgent information, details, or actions. Simple dialogs display a list of items that take immediate effect when selected. Confirmation dialogs...

Alert dialog asking discard draft? Followed by buttons for cancel and discard

Alert dialog

Alert dialogs interrupt users with urgent information, details, or actions.

Simple dialog titled Set backup account. Beneath the title is a list of users

Simple dialog

Simple dialogs display a list of items that take immediate effect when selected.

Confirmation dialog titled Phone ringtone. Beneath the title is a list of choices as radio buttons and text buttons for cancel or ok

Confirmation dialog

Confirmation dialogs require users to confirm a choice before the dialog is dismissed.

A full screen dialog containing a form for creating a new event

Full-screen dialog

Full-screen dialogs fill the entire screen, containing actions that require a series of tasks to complete.


Cross-platform adaptations

On iOS there are components that perform similar functions to dialogs on Android, such as alerts and action sheets. Look at the number of actions and their text length to decide which component (Alert or Action Sheet) to use when adapting a dialog component to iOS.

Use Alerts when there are two actions with short text labels that fit horizontally.

Android
Use a simple dialog when displaying two actions.
iOS
You have the option to use an alert when displaying two actions.

When there are three or more actions with long text labels in a Material dialog, products may use iOS action sheets or bottom sheets.

Android
Stack actions if a text label is long.
iOS
Products may use an iOS action sheet if there are three or more actions.
iOS
Products may use a bottom sheet if there are three or more actions.

Anatomy

Diagram of a dialog with a title, supporting text, and buttons
  1. Container
  2. Title (optional)
  3. Supporting text
  4. Buttons
  5. Scrim

Dialog box and scrim

A dialog is a type of modal window. Access to the rest of the UI is disabled until the modal is addressed. All modal surfaces...

A dialog is a type of modal window. Access to the rest of the UI is disabled until the modal is addressed. All modal surfaces are interruptive by design – their purpose is to have the user focus on content on a surface that appears in front of all other surfaces.

To express that the rest of the app is inaccessible, and to focus attention on the dialog, surfaces behind the dialog are scrimmed. A scrim is a temporary treatment that can be applied to Material surfaces for the purpose of making content on the surface less prominent.


Title

Dialog title and button text should communicate the purpose of any dialog.

A dialog’s purpose should be communicated by its title and button text.

Titles should:

  • Contain a brief, clear statement or question
  • Avoid apologies (“Sorry for the interruption”), alarm (“Warning!”), or ambiguity (“Are you sure?”)
Example dialog asking whether the user wants to use location services
DoThis dialog title poses a specific question, concisely explains what’s involved in the request, and provides clear actions.
Dialog titled Are you sure?
Don'tDon’t use dialog titles that pose an ambiguous question.

Buttons

Dialogs can have buttons side-by-side, and stacked in full width.

Side-by-side buttons (Recommended)

Side-by-side buttons display two text buttons next to one another.

Dialog showing side-by-side text buttons for Disagree and Agree
These side-by-side buttons display buttons provide the actions of “Disagree” and “Agree” as options.

Stacked full-width buttons

Stacked buttons accommodate longer button text. Confirming actions appear above dismissive actions.

Dialog with two full width text buttons, one above the other
Stacked full-width buttons

Elevation

Dialogs are at 24dp elevation, above other content.

Dialogs are displayed at 24dp elevation and can display a shadow. They appear above other content and typically have a scrim below them that covers all app content.


Behavior

Interaction

Dialogs appear without warning, requiring users to stop their current task. They should be used sparingly, as not every choice or setting warrants interruption.

Dialogs appear without warning, requiring users to stop their current task. They should be used sparingly, as not every choice or setting warrants interruption.


Position

Dialogs retain focus until dismissed or an action has been taken, such as choosing a setting. They shouldn’t be obscured by other elements or appear...

Dialogs retain focus until dismissed or an action has been taken, such as choosing a setting. They shouldn’t be obscured by other elements or appear partially on screen, with the exception of full-screen dialogs.


Scrolling

Most dialog content should avoid scrolling. When scrolling is required, the dialog title is pinned at the top, with buttons pinned at the bottom. This...

Most dialog content should avoid scrolling. When scrolling is required, the dialog title is pinned at the top, with buttons pinned at the bottom. This ensures selected content remains visible alongside the title and buttons, even upon scroll.

Dialogs don’t scroll with elements outside of the dialog, such as the background.

When viewing a scrollable list of options, the dialog title and buttons remain fixed.

Dismissing dialogs

Dialogs may be dismissed by:

  • Tapping a "cancel" button, if one is shown
  • Pressing the keyboard Escape key
  • Tapping the scrim (Android, iOS)
  • Tapping the Android system "back" button
  • Using another standard "cancel" or "escape" action, such as iOS' VoiceOver escape gesture

If the user’s ability to dismiss a dialog is disabled, the user must choose a dialog action to proceed.


Transitions

Dialogs enter and exit the screen using a fade transition pattern.

Dialog entering and exiting the screen using a fade transition.

Scaling and adaptation

When scaling layouts for larger screens, adjust a dialog’s visual presentation by setting minimum and maximum values for margins, padding, and container dimensions.

When scaling layouts for larger screens, adjust a dialog’s visual presentation by setting minimum and maximum values for margins, padding, and container dimensions.

Dialogs should maintain a minimum 48dp distance from the leading and trailing edges of a screen. On small screens, dialogs scale vertically until reaching 48dp from the screen’s top and bottom edge. On larger displays, dialogs can increase in size to a maximum width of 560dp. When a dialog reaches the maximum width, it expands or contracts vertically to support content, up to a maximum height of 560dp.

Diagram of a max-width, max-height dialog
Dialogs can reach a maximum height and width of 560dp on large screens.

Dialogs can also swap types as a screen size changes. For example, a full-screen dialog can change into a simple dialog at larger breakpoints.

Example of a dialog on a mobile screen (left) and after transitioning to a tablet screen (right)
1. Full screen dialog on mobile. 2. Simple dialog on a tablet.

Actions

Types of actions

Dialogs present a distinct choice to users through their title, content, and actions. Dialog actions are represented as buttons and allow users confirm or dismiss...

Dialogs present a distinct choice to users through their title, content, and actions. Dialog actions are represented as buttons and allow users confirm or dismiss something.

There are three types of dialog actions:

Confirming actions

To resolve what triggered the dialog, confirming actions confirm a proposed action. These actions can involve removing something, such as “Delete” or “Remove,” if it suits the context. They are placed on the right side of the screen.

Dismissive actions

Dismissive actions dismiss a proposed action, and return the user to the originating screen or step. They are placed directly to the left of a confirming action.

Acknowledgement actions

When user acknowledgement is required to proceed, a single action may be presented. Alternatively, use a snackbar to communicate this type of information.

Dialog with ok button in a disabled state until the user makes a selection
DoDisable confirming actions (1) until a choice is made. Dismissive actions are never disabled.
Button to dismiss the dialog is the right-most button
Don'tDismissive actions (1) are placed to the left of confirming actions.
Dialog titled Not in stock. It contains a short description and one action button labeled OK
DoA single action may be provided only if it’s an acknowledgement.
Text buttons labeled Cancel and Got it
Don'tAvoid presenting users with unclear choices. “Cancel” doesn't make sense here because no clear action is proposed.

Number of actions

Dialogs should contain a maximum of two actions. Rather than adding a third action, an inline expansion can display more information. If more extensive information...

Dialogs should contain a maximum of two actions.

  • If a single action is provided, it must be an acknowledgement action.
  • If two actions are provided, one must be a confirming action, and the other a dismissing action.
  • Providing a third action such as “Learn more” is not recommended as it navigates the user away from the dialog, leaving the dialog task unfinished.

Rather than adding a third action, an inline expansion can display more information. If more extensive information is needed, provide it prior to entering the dialog.

Dialog titled Use location services? It contains three buttons for Learn more, Disagree, and Agree
Don'tThe “Learn more” action (1) navigates away from this dialog, potentially leaving it in an indeterminate state.

Alert dialog

Usage

Alert dialogs interrupt users with urgent information, details, or actions.

Alert dialogs interrupt users with urgent information, details, or actions.


Behavior

To close an alert dialog, one of its actions must be selected.

To close an alert dialog, one of its actions must be selected.

Dialog with buttons for Cancel and Discard
DoThe action “Discard” indicates the outcome of the decision.
Dialog titled Discard draft? containing buttons for Yes and No
Don'tDon’t use action text that fails to indicate what the selection will do. “Cancel” and “Delete” better indicate what will occur in this dialog.

Simple dialog

Usage

Simple dialogs can display items that are immediately actionable when selected. They don’t have text buttons. As simple dialogs are interruptive, they should be used...

Simple dialogs can display items that are immediately actionable when selected. They don’t have text buttons.

As simple dialogs are interruptive, they should be used sparingly. Alternatively, dropdown menus provide options in a non-modal, less disruptive way.


Behavior

A simple dialog allows the following interactions: Simple dialogs allow users to act on selected elements, without action text. For example, users can simply select...

A simple dialog allows the following interactions:

  • Tap an action to choose it and close the dialog
  • Tap outside the dialog to close the dialog without taking an action
Simple dialog titled Set backup account. It contains a list of users
A simple dialog

Simple dialogs without actions

Simple dialogs allow users to act on selected elements, without action text. For example, users can simply select a list item to take action on it.

Simple dialog titled View options. It contains radio buttons for Photos, Movies, and All. At the bottom is a text button for Accept
Don'tDon’t display text buttons in simple dialogs. The choice itself is actionable when tapped.
Simple dialog titled Set backup account. It contains a list of users and a Cancel button
Don'tDon’t include dismissive actions like “Cancel” in a simple dialog. Users can tap anywhere outside the dialog to close it.

Confirmation dialog

Usage

Confirmation dialogs give users the ability to provide final confirmation of a choice before committing to it, so they have a chance to change their...

Confirmation dialogs give users the ability to provide final confirmation of a choice before committing to it, so they have a chance to change their minds if necessary.

If the user confirms a choice, it’s carried out. Otherwise, the user can dismiss the dialog. For example, users can listen to multiple ringtones but only make a final selection upon tapping “OK.”


Behavior

To confirm a choice, the user taps a confirmation action. To cancel, the user taps a dismissive action.

To confirm a choice, the user taps a confirmation action. To cancel, the user taps a dismissive action.

Dialog that allows a user to choose a ringtone. It includes buttons for Cancel and Ok
The user must either confirm a choice or dismiss the dialog before proceeding.

Placement

Confirmation dialogs typically appear as lists, but can appear in a variety of layouts and components, including lists, date pickers, and time pickers.

Confirmation dialogs typically appear as lists, but can appear in a variety of layouts and components, including lists, date pickers, and time pickers.

Confirmation dialog in a list

The user taps a selection and confirms by tapping “OK.”

Confirmation dialog in a date picker

The user selects by tapping a date, then confirms by tapping “OK.”

Confirmation dialog in a time picker

The user selects by moving the clock hand and then confirms by tapping “OK.”


Buttons

Confirmation dialogs provide both confirmation and cancel buttons. After a confirmation button is tapped, a selection is confirmed. If the cancel button is tapped, or...

Confirmation dialogs provide both confirmation and cancel buttons. After a confirmation button is tapped, a selection is confirmed. If the cancel button is tapped, or the area outside the dialog, the action is cancelled.

Dialog asking users to choose one or more labels. It contains buttons for Cancel and Ok
DoProvide confirmation and dismissive buttons.
Dialog asking users to choose one or more labels. It contains only one button that says Ok
Don'tDon’t provide a single action, as it’s unclear how to dismiss the dialog.

Full-screen dialog

Usage

Full-screen dialogs group a series of tasks, such as creating a calendar entry with the event title, date, location, and time. Because they take up...

Full-screen dialogs group a series of tasks, such as creating a calendar entry with the event title, date, location, and time. Because they take up the entire screen, full-screen dialogs are the only dialogs over which other dialogs can appear.

A calendar app launching a full-screen dialog

Full-screen dialogs may be used for content or tasks that meet any of these criteria:

  • Dialogs that include components which require keyboard input, such as form fields
  • When changes aren’t saved instantly
  • When components within the dialog open additional dialogs

Full-screen dialogs are for mobile devices only. For tablet or desktop, use a modal dialog.


Behavior

To save a selection in a full-screen dialog, the user taps “Save.” To discard all changes and exit, the user taps the “X” icon or...

Saving selections

To save a selection in a full-screen dialog, the user taps “Save.” To discard all changes and exit, the user taps the “X” icon or “Back” button.

Confirmation

The confirmation action is disabled until all mandatory fields are filled. Use descriptive verbs such as “Save,” “Send,” “Share,” “Update,” or “Create.” Don’t use vague terms such as “Done,” “OK” or “Close.”

  • If no changes have been made, the dialog closes and no discard confirmation is required
  • If the user has made changes, the user is prompted to confirm the discard action
Full screen dialog for adding an event. It includes a Close button to the right of the title
Don'tA “Close” button (1) is vague because it does not indicate whether changes will be saved or discarded.

Dialog windows

Launching a full-screen dialog temporarily resets the app’s perceived elevation, allowing simple menus or dialogs to appear above the full-screen dialog.

A calendar app launching a full-screen dialog, which launches a confirmation dialog, and alert dialog.

Layout

Full-screen dialogs cover the screen and don’t appear as a floating modal window. Place confirmation and dismissive actions in the top app bar. Because full-screen...

Full-screen dialogs cover the screen and don’t appear as a floating modal window.

Actions

Place confirmation and dismissive actions in the top app bar.

Navigation

Because full-screen dialogs can only be completed, dismissed, or closed, only use the close “X” navigation button.

Full screen dialog showing a back arrow instead of a close icon
Don'tAvoid any navigation icon other than “X.” The up arrow (1) indicates the view’s state is being saved, which isn’t the case in a full-screen dialog.

Titles

Titles should be succinct. They can wrap to a second line if necessary, and be truncated. If there are long titles, or titles of variable lengths (such as translations), place them in the content area instead of the app bar.

Full screen dialog showing a long German title that has been truncated, reducing legibility
CautionAvoid placing long titles in a dialog’s top app bar (1), as the truncated text may lead to misunderstanding.
Full screen dialog showing a short concise German title, with a long title as part of the body content
DoFind ways to shorten app bar text, and place longer titles into the content area (1) of a full-screen dialog.

Theming

Crane Material theme

This travel app’s dialogs have been customized using Material Theming. Areas of customization include color, typography, and shape. Crane is a travel app that uses...

Color

Crane’s dialogs use custom color on five elements: the container, title text, supporting text, button text, and scrim.

Diagram showing five custom colors applied across elements of the Crane app
Element Category Attribute Value
Container Surface Color
Opacity
#FFFFFF
100%
Title text On Surface Color
Opacity
#000000
87%
Supporting text On Surface Color
Opacity
#000000
60%
Button text Primary Color
Opacity
#5C1349
100%
Scrim On Surface Color
Opacity
#000000
32%

Typography

Crane’s dialogs use custom typography for title text, supporting text, and button text.

Custom values for dialog typography including the title, body, and button text
Element Category Attribute Value
Title text H6 Typeface
Font
Size
Case
Raleway
Bold
20
Title case
Supporting text Body 1 Typeface
Font
Size
Case
Raleway
Medium
16
Sentence case
Button text Button Typeface
Font
Size
Case
Raleway
SemiBold
14
All caps

Shape

Crane’s dialog boxes have custom corner shapes.

Diagram of 16dp rounded corners
Element Category Value
Container Top left corner
Top right corner
Bottom right corner
Bottom left corner
Rounded 16dp
Rounded 16dp
Rounded 16dp
Rounded 16dp

Reply Material theme

This email app’s dialogs have been customized using Material Theming. Areas of customization include color, typography, and shape. Reply is an email app that uses...

Color

Reply’s dialogs use custom color on five elements: the dialog box, title text, supporting text, button text, and scrim.

Diagram of five custom colors being applied across elements in the Reply app
Element Category Attribute Value
Container Surface Color
Opacity
#000000
100%
Title text On Surface Color
Opacity
#232F34
100%
Supporting text On Surface Color
Opacity
#232F34
100%
Button text Primary Color
Opacity
#344955
100%
Scrim On Surface Color
Opacity
#232F34
32%

Typography

Reply’s dialogs use custom typography for title text, supporting text, and button text.

Custom values for dialog typography including the title, body, and button text
Element Category Attribute Value
Title text H6 Typeface
Font
Size
Case
Work Sans
Bold
21
Sentence case
Supporting text Body 1 Typeface
Font
Size
Case
Work Sans
Regular
16
Sentence case
Button text Button Typeface
Font
Size
Case
Work Sans
SemiBold
15
Sentence case

Shape

Reply’s dialog boxes have custom corner shapes.

Square corners for Reply’s custom theme
Element Category Attribute Value
Container Medium component Family
Size
Cut
0;0;0;0dp

Specs

Mobile

20dp #000000de 14dp #00000099 #ffffff R255 G255 B255 Elevation 24dp All corners Rounded: 4dp Scrim #000000, opacity:32% All measurements are displayed in device-independent pixels (dps)...

Simple dialog

  • Measurement 64
  • Measurement 24
  • Measurement 20
  • Measurement 40
  • Measurement 56
  • 4040
 

Alert dialog

  • Measurement 52
  • Measurement 24
  • Measurement 24
  • Measurement 38
  • Measurement 28
  • Measurement 280
  • Measurement 8
  • Measurement 8
  • Measurement 8
  • Measurement 8
 

Confirmation dialog

  • Measurement 24
  • Measurement 24
  • Measurement 52
  • Measurement 280
  • Measurement 40
  • Measurement 36
  • Measurement 8
  • Measurement 8
  • Measurement 8
  • Measurement 8
  • Measurement 28
 

Confirmation dialog (scrolling)

  • Measurement 64
  • Measurement 52
  • Measurement 280
  • Measurement 24
  • Measurement 32
  • Measurement 24
  • Measurement 40
  • Measurement 8
  • Measurement 8
  • Measurement 8
  • Measurement 8
  • Measurement 48
  • Measurement C
  • 2424
 

Confirmation dialog with long actions

  • Measurement 24
  • Measurement 24
  • Measurement 36
  • Measurement 28
  • Measurement 8
  • Measurement 12
  • Measurement 8
  • Measurement 40
 

Full-screen dialog

  • Measurement 16
  • Measurement 32
  • Measurement 8
  • Measurement 8
  • Measurement 12
  • Measurement 56
  • Measurement 24
  • Measurement 38
 

Desktop

20dp #000000de 16dp #00000099 14dp #6200ee #ffffff R255 G255 B255 #ffffff R255 G255 B255 Elevation 24dp All corners Rounded: 4dp Text Buttons Height The height...

Mobile alert

  • Measurement 24
  • Measurement 8
  • Measurement 52
  • Measurement 182
  • Measurement 24
  • Measurement 40
  • Measurement 8
  • Measurement 560
  • Measurement 8
  • Measurement 8
  • Measurement 28
  • Measurement 36
 

Using dialogs

Before you can use Material dialogs, you need to add a dependency to the Material Components for Android library. For more information, go to the Getting started page.

Making dialogs accessible

The contents within a dialog should follow their own accessibility guidelines, such as an icon on a title having a content description via the android:contentDescription attribute set in the MaterialAlertDialog.MaterialComponents.Title.Icon style or descendant.

Adding full width buttons

The buttons in a dialog can be made to span the full width of the dialog by using the theme overrides R.style.ThemeOverlay_MaterialComponents_MaterialAlertDialog_FullWidthButtons or R.style.ThemeOverlay_MaterialComponents_MaterialAlertDialog_Centered_FullWidthButtons.

The following example shows an alert dialog with a long message and two full width buttons.

"Dialog with decline and accept buttons that span the full width"

In code:

Types

There are four types of dialogs: 1. Alert dialog, 2. Simple dialog, 3. Confirmation dialog, 4. Full-screen dialog

Examples of the four types of dialogs.

Dialogs

A dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.

Dialogs are purposefully interruptive, so they should be used sparingly.

Dialog examples

API and source code:

Alert dialog

Alert dialogs interrupt users with urgent information, details, or actions.

The following example shows an alert dialog.

"Dialog with title, and text and purple buttons to cancel, decline or accept"

In code:

Simple dialog

Simple dialogs can display items that are immediately actionable when selected. They don’t have text buttons.

As simple dialogs are interruptive, they should be used sparingly. Alternatively, dropdown menus provide options in a non-modal, less disruptive way.

The following example shows a simple dialog.

"Dialog with title and three list items"

In code:

Confirmation dialog

Confirmation dialogs give users the ability to provide final confirmation of a choice before committing to it, so they have a chance to change their minds if necessary.

If the user confirms a choice, it’s carried out. Otherwise, the user can dismiss the dialog. For example, users can listen to multiple ringtones but only make a final selection upon tapping “OK.”

The following example shows a confirmation dialog.

"Dialog with title, three items with radio buttons, and purple text buttons to
cancel and accept"

For multiple choice items you can do as follows:

Full-screen dialog

Full-screen dialogs group a series of tasks, such as creating a calendar entry with the event title, date, location, and time. Because they take up the entire screen, full-screen dialogs are the only dialogs over which other dialogs can appear.

There is no specific Material implementation of a full-screen dialog. You can implement it by using a DialogFragment as explained in the Android Developer guides.

Anatomy and key properties

A dialog has a container, content (either supporting text or a set of items of a particular type), a background scrim, and, optionally, title and buttons.

anatomy

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

Container attributes

ElementAttributeRelated methodsDefault value
ColorN/AN/A?attr/colorSurface
Shapeapp:shapeAppearance
app:shapeAppearanceOverlay
N/A?attr/shapeAppearanceMediumComponent
Background inset start and endapp:backgroundInsetStart
app:backgroundInsetEnd
setBackgroundInsetStart
setBackgroundInsetEnd
24dp
Background inset top and bottomapp:backgroundInsetTop
app:backgroundInsetBottom
setBackgroundInsetTop
setBackgroundInsetBottom
80dp

Title attributes

ElementAttributeRelated methodsDefault value
Text labelN/AsetTitle
setCustomTitle
null
Text colorandroid:textColorN/A?attr/colorOnSurface at 87%
Typographyandroid:textAppearanceN/A?attr/textAppearanceSubtitle1
IconN/AsetIcon
setIconAttribute
null

Content attributes

Supporting text

ElementAttributeRelated methodsDefault value
TextN/AsetMessagenull
Colorandroid:textColorN/A?attr/colorOnSurface at 60%
Typographyandroid:textAppearanceN/A?attr/textAppearanceBody2

List item

ElementAttributeRelated methodsDefault value
List item layoutapp:listItemLayoutsetItems@layout/mtrl_alert_select_dialog_item
List item layout styleN/AN/A?attr/materialAlertDialogBodyTextStyle
List item text colorandroid:textColorN/A?attr/colorOnSurface at 60%
List item typographyandroid:textAppearanceN/A?attr/textAppearanceBody2
Multi choice item layoutapp:multiChoiceItemLayoutsetMultiChoiceItems@layout/mtrl_alert_select_dialog_multichoice
Single choice item layoutapp:singleChoiceItemLayoutsetSingleChoiceItems@layout/mtrl_alert_select_dialog_singlechoice
Multi/single choice item styleandroid:checkedTextViewStyleN/A@style/Widget.MaterialComponents.CheckedTextView
Multi/single choice item text colorandroid:textColorN/A?attr/colorOnSurface at 60%
Multi/single choice item typographyandroid:textAppearanceN/A?attr/textAppearanceBody1

Note: You can set any view to be the content of your dialog via the setView method.

Buttons attributes

ElementAttributeRelated methodsDefault value
Buttons theme attributesapp:buttonBar*ButtonStyleN/A@style/Widget.MaterialComponents.Button.TextButton.Dialog
Buttons (neutral/negative/positive)N/Aset*Buttonnull
IconsN/Aset*ButtonIconnull

For specific button attributes, see the Buttons documentation.

Scrim attributes

ElementAttributeRelated methodsDefault value
Dim ammountandroid:backgroundDimAmountN/A32%

Theme overlays

ElementTheme overlay
Default theme overlayThemeOverlay.MaterialComponents.MaterialAlertDialog
Centered theme overlayThemeOverlay.MaterialComponents.MaterialAlertDialog.Centered

Default theme overlay attribute: ?attr/materialAlertDialogTheme

Theme attributes

ElementTheme attributeDefault value
Default style?attr/alertDialogStyle@style/MaterialAlertDialog.MaterialComponents
Title text style?attr/materialAlertDialogTitleTextStyle@style/MaterialAlertDialog.MaterialComponents.Title.Text
Supporting text style?attr/materialAlertDialogBodyTextStyle@style/MaterialAlertDialog.MaterialComponents.Body.Text

See full list of styles, attributes, and theme overlays.

Theming dialogs

A dialog supports Material Theming and can be customized in terms of color, typography and shape.

Dialog theming example

API and source code:

The following example shows a dialog with Material Theming.

Dialog with title and text buttons in brown and selected radio button in pink

Implementing dialog theming

Setting the theme attribute materialAlertDialogTheme to your custom ThemeOverlay will affect all dialogs.

In res/values/themes.xml:

In res/values/styles.xml:

Or if you want to only change one specific dialog, pass the themeResId to the constructor:

No Android implementation guidance available

Using dialogs

A dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.

Dialogs are purposefully interruptive, so they should be used sparingly.

For additional guidance, refer to the Material guidelines.

Installation

Styles

Note: Styles for any components you intend to include within dialogs (e.g. List, Checkboxes, etc.) must also be imported.

JavaScript Instantiation

Note: See Importing the JS component for more information on how to import JavaScript.

MDC Dialog makes no assumptions about what will be added to the mdc-dialog__content element. Any list, checkboxes, etc. must also be instantiated. If your dialog contains any layout-sensitive components, you should wait until MDCDialog:opened is emitted to instantiate them (or call layout on them) so that the dialog's transition finishes first.

For example, to instantiate an MDC List inside of a simple or confirmation dialog:

Note: Mispositioned or incorrectly-sized elements (e.g. ripples, floating labels, notched outlines) are a strong indication that child components are being instantiated before the dialog has finished opening.

Making dialogs accessible

Using aria-hidden as a fallback for aria-modal

aria-modal is part of the ARIA 1.1 specification, and indicates to screen readers that they should confine themselves to a single element. We recommend adding aria-modal="true" to the root element of its DOM structure.

However, not all user agents and screen readers properly interpret this attribute.

The fallback is to use aria-hidden using aria-hidden="true" to all static content beneath the dialog when the dialog is open. This will be easiest to achieve if all non-modal elements are under a single common ancestor under the body, so that aria-hidden can be applied to one element.

Note: The example above intentionally listens to the opened (not opening) event and the closing (not closed) event in order to avoid additional jumping between elements by screen readers due to one element becoming hidden before others become visible.

Alert dialog

Alert dialogs interrupt users with urgent information, details, or actions.

Alert dialog: discard

Alert dialog example

Simple dialog

Simple dialogs can display items that are immediately actionable when selected. They don’t have text buttons.

As simple dialogs are interruptive, they should be used sparingly. Alternatively, dropdown menus provide options in a non-modal, less disruptive way.

Simple dialog: selection

Simple dialog example

Note: Note the inclusion of the mdc-list--avatar-list class, which aligns with the Simple Dialog spec.

Confirmation dialog

Confirmation dialogs give users the ability to provide final confirmation of a choice before committing to it, so they have a chance to change their minds if necessary.

If the user confirms a choice, it’s carried out. Otherwise, the user can dismiss the dialog. For example, users can listen to multiple ringtones but only make a final selection upon tapping “OK.”

Confirmation dialog: selection confirmation

Confirmation dialog example

Note: In the example above, the Cancel button intentionally has the close action to align with the behavior of clicking the scrim or pressing the Escape key, allowing all interactions involving dismissal without taking an action to be detected the same way.

Full-screen dialog

Full-screen dialogs group a series of tasks, such as creating a calendar entry with the event title, date, location, and time.

Full-screen dialog: event

Full-screen dialog example

Note: Full-screen dialogs are intended for mobile/small-screen devices. The dialog's size will adapt to the screen size, and so becomes modal if used on larger screen sizes.

Additional Information

Dialog actions

All dialog variants support the concept of dialog actions. Any element within a dialog may include the data-mdc-dialog-action attribute to indicate that interacting with it should close the dialog with the specified action. This action is then reflected via event.detail.action in the MDCDialog:closing and MDCDialog:closed events.

Additionally, two interactions have defined actions by default:

  • Clicking on the scrim
  • Pressing the Escape key within the dialog

Both of these map to the close action by default. This can be accessed and customized via the component's scrimClickAction and escapeKeyAction properties, respectively.

Setting either of these properties to an empty string will result in that interaction being disabled (i.e. the dialog will no longer close in response to the interaction). Exercise caution when doing this - it should always be possible for a user to dismiss the dialog.

Any action buttons within the dialog which equate strictly to a dismissal with no further action should also use the close action; this will make it easy to handle all such interactions consistently, while separately handling other actions.

Action button arrangement

As indicated in the Dialog design article, buttons within the mdc-dialog__actions element are arranged horizontally by default, with the confirming action last.

In cases where the button text is too long for all buttons to fit on a single line, the buttons are stacked vertically, with the confirming action first.

MDC Dialog detects and handles this automatically by default, reversing the buttons when applying the stacked layout. This automatic behavior can be disabled by setting autoStackButtons to false on the component instance:

This will also be disabled if the mdc-dialog--stacked modifier class is applied manually to the root element before the component is instantiated, but note that dialog action button labels are recommended to be short enough to fit on a single line if possible.

Default action button

MDC Dialog supports indicating that one of its action buttons represents the default action, triggered by pressing the Enter key. This can be used e.g. for single-choice Confirmation Dialogs to accelerate the process of making a selection, avoiding the need to tab through to the appropriate button to confirm the choice.

To indicate that a button represents the default action, add the data-mdc-dialog-button-default data attribute. For example:

Actions and selections

Dialogs which require making a choice via selection controls should initially disable any button which performs an action if no choice is selected by default. MDC Dialog does not include built-in logic for this, since it aims to remain as unopinionated as possible regarding dialog contents, aside from relaying information on which action is taken.

Style customizations

CSS classes

CSS ClassDescription
mdc-dialogMandatory. The root DOM element containing the surface and the container.
mdc-dialog__scrimMandatory. Semitransparent backdrop that displays behind a dialog.
mdc-dialog__containerMandatory. Wrapper element needed to ensure flexbox behavior in IE 11.
mdc-dialog__surfaceMandatory. The bounding box for the dialog's content.
mdc-dialog__titleOptional. Brief summary of the dialog's purpose.
mdc-dialog__contentOptional. Primary content area. May contain a list, a form, or prose.
mdc-dialog__actionsOptional. Footer area containing the dialog's action buttons.
mdc-dialog__buttonOptional. Individual action button. Typically paired with mdc-button.
mdc-dialog--openOptional. Indicates that the dialog is open and visible.
mdc-dialog--openingOptional. Applied automatically when the dialog is in the process of animating open.
mdc-dialog--closingOptional. Applied automatically when the dialog is in the process of animating closed.
mdc-dialog--scrollableOptional. Applied automatically when the dialog has overflowing content to warrant scrolling.
mdc-dialog--stackedOptional. Applied automatically when the dialog's action buttons can't fit on a single line and must be stacked.

Sass mixins

MixinDescription
container-fill-color($color)Sets the fill color of the dialog.
scrim-color($color, $opacity)Sets the color of the scrim behind the dialog.
title-ink-color($color, $opacity)Sets the color of the dialog's title text.
content-ink-color($color, $opacity)Sets the color of the dialog's content text.
content-padding($padding-top, $padding-right, $padding-bottom, $padding-left)Sets the padding of the dialog's content.
scroll-divider-color($color, $opacity)Sets the color of the dividers which display around scrollable content.
shape-radius($radius, $rtl-reflexive)Sets the rounded shape to dialog surface with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
min-width($min-width)Sets the minimum width of the dialog (defaults to 280px).
max-width($max-width, $margin)Sets the maximum width of the dialog (defaults to 560px max width and 16px margins).
max-height($max-height, $margin)Sets the maximum height of the dialog (defaults to no max height and 16px margins).

Note: The max-width and max-height mixins only apply their maximum when the viewport is large enough to accommodate the specified value when accounting for the specified margin on either side. When the viewport is smaller, the dialog is sized such that the given margin is retained around the edges.

Other customizations

Data AttributesDescription
data-mdc-dialog-button-defaultOptional. Add to a button to indicate that it is the default action button (see Default Action Button section above).
data-mdc-dialog-initial-focusOptional. Add to an element to indicate that it is the element to initially focus on after the dialog has opened.

MDCDialog properties and methods

PropertyValue TypeDescription
isOpenboolean (read-only)Proxies to the foundation's isOpen method.
escapeKeyActionstringProxies to the foundation's getEscapeKeyAction and setEscapeKeyAction methods.
scrimClickActionstringProxies to the foundation's getScrimClickAction and setScrimClickAction methods.
autoStackButtonsbooleanProxies to the foundation's getAutoStackButtons and setAutoStackButtons methods.
Method SignatureDescription
layout() => voidRecalculates layout and automatically adds/removes modifier classes like --scrollable.
open() => voidOpens the dialog.
close(action: string?) => voidCloses the dialog, optionally with the specified action indicating why it was closed.

Events

Event Nameevent.detailDescription
MDCDialog:opening{}Indicates when the dialog begins its opening animation.
MDCDialog:opened{}Indicates when the dialog finishes its opening animation.
MDCDialog:closing{action: string?}Indicates when the dialog begins its closing animation. action represents the action which closed the dialog.
MDCDialog:closed{action: string?}Indicates when the dialog finishes its closing animation. action represents the action which closed the dialog.

Usage within web frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Dialog for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

MDCDialogAdapter

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanReturns whether the given class exists on the root element.
addBodyClass(className: string) => voidAdds a class to the <body>.
removeBodyClass(className: string) => voidRemoves a class from the <body>.
eventTargetMatches(target: EventTarget | null, selector: string) => voidReturns true if the target element matches the given CSS selector, otherwise false.
trapFocus(initialFocusEl: HTMLElement | null) => voidSets up the DOM such that keyboard navigation is restricted to focusable elements within the dialog surface (see Handling Focus Trapping below for more details). Moves focus to initialFocusEl, if set.
releaseFocus() => voidRemoves any effects of focus trapping on the dialog surface (see Handling Focus Trapping below for more details).
getInitialFocusEl() => HTMLElement | nullReturns the data-mdc-dialog-initial-focus element to add focus to after the dialog has opened.
isContentScrollable() => booleanReturns true if mdc-dialog__content can be scrolled by the user, otherwise false.
areButtonsStacked() => booleanReturns true if mdc-dialog__action buttons (mdc-dialog__button) are stacked vertically, otherwise false if they are side-by-side.
getActionFromEvent(event: Event) => string | nullRetrieves the value of the data-mdc-dialog-action attribute from the given event's target, or an ancestor of the target.
clickDefaultButton() => voidInvokes click() on the data-mdc-dialog-button-default element, if one exists in the dialog.
reverseButtons() => voidReverses the order of action buttons in the mdc-dialog__actions element. Used when switching between stacked and unstacked button layouts.
notifyOpening() => voidBroadcasts an event denoting that the dialog has just started to open.
notifyOpened() => voidBroadcasts an event denoting that the dialog has finished opening.
notifyClosing(action: string) {}Broadcasts an event denoting that the dialog has just started closing. If a non-empty action is passed, the event's detail object should include its value in the action property.
notifyClosed(action: string) {}Broadcasts an event denoting that the dialog has finished closing. If a non-empty action is passed, the event's detail object should include its value in the action property.

MDCDialogFoundation

Method SignatureDescription
open()Opens the dialog.
close(action: string)Closes the dialog, optionally with the specified action indicating why it was closed.
isOpen() => booleanReturns whether the dialog is open.
layout()Recalculates layout and automatically adds/removes modifier classes e.g. --scrollable.
getEscapeKeyAction() => stringReturns the action reflected when the Escape key is pressed.
setEscapeKeyAction(action: string)Sets the action reflected when the Escape key is pressed. Setting to '' disables closing the dialog via Escape key.
getScrimClickAction() => stringReturns the action reflected when the scrim is clicked.
setScrimClickAction(action: string)Sets the action reflected when the scrim is clicked. Setting to '' disables closing the dialog via scrim click.
getAutoStackButtons() => booleanReturns whether stacked/unstacked action button layout is automatically handled during layout logic.
setAutoStackButtons(autoStack: boolean) => voidSets whether stacked/unstacked action button layout is automatically handled during layout logic.
handleClick(event: MouseEvent)Handles click events on or within the dialog's root element.
handleKeydown(event: KeyboardEvent)Handles keydown events on or within the dialog's root element.
handleDocumentKeydown(event: Event)Handles keydown events on or within the document while the dialog is open.
getSuppressDefaultPressSelector() => stringReturns the selector string for elements that suppress the default dialog press action, such as pressing enter in a textarea.
setSuppressDefaultPressSelector(selector: string)Customize the selector string to suppress the default dialog press action. An empty string indicates that no elements should suppress the default action.

Event handlers

When wrapping the Dialog foundation, the following events must be bound to the indicated foundation methods:

EventTargetFoundation HandlerRegisterDeregister
click.mdc-dialog (root)handleClickDuring initializationDuring destruction
keydown.mdc-dialog (root)handleKeydownDuring initializationDuring destruction
keydowndocumenthandleDocumentKeydownOn MDCDialog:openingOn MDCDialog:closing
resizewindowlayoutOn MDCDialog:openingOn MDCDialog:closing
orientationchangewindowlayoutOn MDCDialog:openingOn MDCDialog:closing

The util API

External frameworks and libraries can use the following utility methods from the util module when implementing their own component.

Method SignatureDescription
createFocusTrapInstance(surfaceEl: Element, focusTrapFactory: function(): !FocusTrap, initialFocusEl: ?Element) => !FocusTrapCreates a properly configured focus-trap instance.
isScrollable(el: Element | null) => booleanDetermines if the given element is scrollable.
areTopsMisaligned(els: Element[]) => booleanDetermines if two or more of the given elements have different offsetTop values.

Handling focus trapping

In order for dialogs to be fully accessible, they must conform to the guidelines outlined in:

The main implication of these guidelines is that the only focusable elements are those contained within a dialog surface.

Trapping focus correctly for a modal dialog requires a complex set of events and interaction patterns that we feel is best not duplicated within the logic of this component. Furthermore, frameworks and libraries may have their own ways of trapping focus that framework authors may want to make use of. For this reason, we have two methods on the adapter that should be used to handle focus trapping:

  • trapFocus() is called when the dialog is open and should set up focus trapping adhering to the ARIA practices in the link above.
  • releaseFocus() is called when the dialog is closed and should tear down any focus trapping set up when the dialog was open.

The MDCDialog component uses the focus-trap package to handle this. You can use util.createFocusTrapInstance() (see below) to easily create a focus trapping solution for your component code.

Note: iOS platform doesn't seem to register currently focused element via document.activeElement which causes releasing focus to last focused element fail.

createFocusTrapInstance()

Given a dialog surface element an optional focusTrap factory function, and an optional initial element to focus, such that:

  • The focus is trapped within the surfaceEl
  • The initialFocusEl receives focus when the focus trap is activated
    • If omitted, defaults to the first focusable element in surfaceEl
  • Closing the dialog in any way (including pressing Escape or clicking outside the dialog) deactivates focus trapping
  • Focus is returned to the previously focused element before the focus trap was activated

This focus trap instance can be used to implement the trapFocus and releaseFocus adapter methods by calling instance.activate() and instance.deactivate() respectively within those methods.

The focusTrapFactory can be used to override the focus-trap function used to create the focus trap. Its API is the same as focus-trap's createFocusTrap (which is what it defaults to). You can pass in a custom function for mocking out the actual function within tests, or to modify the arguments passed to the function before it's called.

No Web implementation guidance available

Using dialogs

A dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.

Dialogs are purposefully interruptive, so they should be used sparingly.

Before you can use Material dialogs, you need to import the Material Components package for Flutter: package:flutter/material.dart.

You need to use a MaterialApp.

For more information on getting started with the Material for Flutter, go to the Flutter Material library page.

Types

There are four types of dialogs: 1. Alert, 2. Simple, 3. Confirmation, 4. Full-screen

Hero image of the 4 types of dialogs

Making dialogs accessible

Flutter's APIs support accessibility setting for large fonts, screen readers, and sufficient contrast. For more information, go to Flutter's accessibility and internationalization pages.

For more guidance on writing labels, go to our page on how to write a good accessibility label.

Alert dialog

Alert dialogs interrupt users with urgent information, details, or actions.

Alert dialog example

AlertDialog

The following example shows an alert dialog.

"Alert dialog example for Flutter."

Alert dialog anatomy and key properties

The alert dialog contains the following:

alert dialog anatomy diagram

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

Container attributes

 Properties
ColorbackgroundColor
Shapeshape
Elevationelevation

Title attributes

 Properties
Text labeltitle
Colorstyle on title when using a Text
Typographystyle on title when using a Text

Supporting text attributes

 Properties
Text labelcontent
Colorstyle on content when using a Text
Typographystyle on content when using a Text

Buttons attributes

 Properties
Buttonsactions

Simple dialog

Simple dialogs can display items that are immediately actionable when selected. They don’t have text buttons.

As simple dialogs are interruptive, they should be used sparingly. Alternatively, dropdown menus provide options in a non-modal, less disruptive way.

Simple dialog example

SimpleDialog

The following example shows a simple dialog.

"Simple dialog example for Flutter."

Simple dialog anatomy and key properties

A simple dialog contains the following:

simple dialog anatomy diagram

  1. Container
  2. Title
  3. List item
    1. Supporting visual
    2. Primary text
  4. Button
  5. Scrim

Container attributes

 Properties
ColorbackgroundColor
Shapeshape
Elevationelevation

Title attributes

 Properties
Text labeltitle
Colorstyle on title when using a Text
Typographystyle on title when using a Text

List item supporting visual attributes

 Properties
Optionschildren (Use SimpleDialogOption and customize its child parameter as needed.)

Confirmation dialog

Confirmation dialogs give users the ability to provide final confirmation of a choice before committing to it, so they have a chance to change their minds if necessary.

If the user confirms a choice, it’s carried out. Otherwise, the user can dismiss the dialog. For example, users can listen to multiple ringtones but only make a final selection upon tapping “OK.”

NOTE: There is no explicit confirmation dialog in Flutter but this can be built using the Dialog widget as a blank slate and providing your own custom child.

Full-screen dialog

Full-screen dialogs group a series of tasks, such as creating a calendar entry with the event title, date, location, and time. Because they take up the entire screen, full-screen dialogs are the only dialogs over which other dialogs can appear.

Full-screen dialog example

MaterialPageRoute

To use a full-screen dialog, simply set the fullscreenDialog to true when pushing a new MaterialPageRoute.

Full-screen dialog anatomy

The full-screen dialog contains the following properties:

full-screen dialog anatomy

  1. Title
  2. Icon Button
  3. Buttons
  4. Scrim

Dialog theming

Dialog theming example

The following example shows a simple dialog with the Material Shrine Theme.

Simple dialog with Shrine theming

No Flutter implementation guidance available

Using dialogs

Installing

In order to use Dialogs with Cocoapods first add the Dialogs subspec to your Podfile:

Then, run the installer:

After that, import the relevant target or file.

Swift

Objective-C

Dialogs classes

Dialogs on iOS consist of three classes:

  1. MDCAlertController provides a basic alert interface with support for things like title text, message text, and optional accessory views.
  2. 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.
  3. MDCDialogPresentationController is the UIPresentationController subclass provided by MDCDialogTransitionController.

Making dialogs accessible

MDCDialogPresentationController Accessibility

As MDCDialogPresentationController 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.

Alert dialog

Example alert dialog with lorem ipsum sample text.

Alerts are the only type of dialog supported on iOS. Consider using the ActionSheet component in situations where one of the unsupported dialog types would have been appropriate.

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

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

Objective-C

Custom alert dialog example

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

Swift

Objective-C

Anatomy and key properties

The following is an anatomy diagram of a Material dialog:

Dialog anatomy diagram with title, description, and Cancel and Accept buttons

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

Container attributes

 AttributeRelated methodsDefault value
Colorview.backgroundColor-setBackgroundColor:
-backgroundColor
Surface color
ShapecornerRadius-setCornerRadius:
-cornerRadius
4

Title attributes

 AttributeRelated methodsDefault value
Text labeltitle-setTitle:
-title
nil
Text colortitleColor-setTitleColor:
-titleColor
nil
TypographytitleFont-setTitleFont:
-titleFont
Headline 6

Content attributes

 AttributeRelated methodsDefault value
Textmessage-setMessage:
-message
nil
Text colormessageColor-setMessageColor:
-messageColor
nil
TypographymessageFont-setMessageFont:
-messageFont
Body 1

Theming

Shrine-themed dummy dialog with Accept and Cancel buttons

You can theme a Material dialog using a container scheme and a 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:

Then run the installer:

Then import the theming extension 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

Objective-C

Theming Actions

MDCAlertController actions have emphasis values which affect how the dialog's buttons will be themed. .high, .medium, and .low emphasis are supported.

Swift

Objective-C

No iOS implementation guidance available

Up next