Dialogs

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

Contents

Using dialogs
Alert dialog
Simple dialog
Confirmation dialog
Full-screen dialog
Theming

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.

MaterialAlertDialogBuilder(context)
    // Add customization options here
    .show()

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.

Types

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

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:

MaterialAlertDialogBuilder
- Class description
- Class source

Alert dialog

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

The following example shows an alert dialog.

In code:

MaterialAlertDialogBuilder(context)
        .setTitle(resources.getString(R.string.title))
        .setMessage(resources.getString(R.string.supporting_text))
        .setNeutralButton(resources.getString(R.string.cancel)) { dialog, which ->
            // Respond to neutral button press
        }
        .setNegativeButton(resources.getString(R.string.decline)) { dialog, which ->
            // Respond to negative button press
        }
        .setPositiveButton(resources.getString(R.string.accept)) { dialog, which ->
            // Respond to positive button press
        }
        .show()

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.

In code:

val items = arrayOf("Item 1", "Item 2", "Item 3")

MaterialAlertDialogBuilder(context)
        .setTitle(resources.getString(R.string.title))
        .setItems(items) { dialog, which ->
             // Respond to item chosen
         }
        .show()

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.

val singleItems = arrayOf("Item 1", "Item 2", "Item 3")
val checkedItem = 1

MaterialAlertDialogBuilder(context)
        .setTitle(resources.getString(R.string.title))
        .setNeutralButton(resources.getString(R.string.cancel)) { dialog, which ->
            // Respond to neutral button press
        }
        .setPositiveButton(resources.getString(R.string.ok)) { dialog, which ->
            // Respond to positive button press
        }
        // Single-choice items (initialized with checked item)
        .setSingleChoiceItems(singleItems, checkedItem) { dialog, which ->
             // Respond to item chosen
         }
        .show()

For multiple choice items you can do as follows:

val multiItems = arrayOf("Item 1", "Item 2", "Item 3")
val checkedItems = booleanArrayOf(true, false, false, false)

MaterialAlertDialogBuilder(context)
        ...
        //Multi-choice items (initialized with checked items)
        .setMultiChoiceItems(multiItems, checkedItems) { dialog, which, checked ->
            // Respond to item chosen
        }
        .show()

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.

Container
Title (optional)
Content
Buttons (optional)
Scrim

Container attributes

Element	Attribute	Related methods	Default value
Color	N/A	N/A	`?attr/colorSurface`
Shape	`app:shapeAppearance` `app:shapeAppearanceOverlay`	N/A	`?attr/shapeAppearanceMediumComponent`
Background inset start and end	`app:backgroundInsetStart` `app:backgroundInsetEnd`	`setBackgroundInsetStart` `setBackgroundInsetEnd`	`24dp`
Background inset top and bottom	`app:backgroundInsetTop` `app:backgroundInsetBottom`	`setBackgroundInsetTop` `setBackgroundInsetBottom`	`80dp`

Title attributes

Element	Attribute	Related methods	Default value
Text label	N/A	`setTitle` `setCustomTitle`	`null`
Text color	`android:textColor`	N/A	`?attr/colorOnSurface` at 87%
Typography	`android:textAppearance`	N/A	`?attr/textAppearanceSubtitle1`
Icon	N/A	`setIcon` `setIconAttribute`	`null`

Content attributes

Supporting text

Element	Attribute	Related methods	Default value
Text	N/A	`setMessage`	`null`
Color	`android:textColor`	N/A	`?attr/colorOnSurface` at 60%
Typography	`android:textAppearance`	N/A	`?attr/textAppearanceBody2`

List item

Element	Attribute	Related methods	Default value
List item layout	`app:listItemLayout`	`setItems`	`@layout/mtrl_alert_select_dialog_item`
List item layout style	N/A	N/A	`?attr/materialAlertDialogBodyTextStyle`
List item text color	`android:textColor`	N/A	`?attr/colorOnSurface` at 60%
List item typography	`android:textAppearance`	N/A	`?attr/textAppearanceBody2`
Multi choice item layout	`app:multiChoiceItemLayout`	`setMultiChoiceItems`	`@layout/mtrl_alert_select_dialog_multichoice`
Single choice item layout	`app:singleChoiceItemLayout`	`setSingleChoiceItems`	`@layout/mtrl_alert_select_dialog_singlechoice`
Multi/single choice item style	`android:checkedTextViewStyle`	N/A	`@style/Widget.MaterialComponents.CheckedTextView`
Multi/single choice item text color	`android:textColor`	N/A	`?attr/colorOnSurface` at 60%
Multi/single choice item typography	`android:textAppearance`	N/A	`?attr/textAppearanceBody1`

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

Buttons attributes

Element	Attribute	Related methods	Default value
Buttons theme attributes	`app:buttonBar*ButtonStyle`	N/A	`@style/Widget.MaterialComponents.Button.TextButton.Dialog`
Buttons (neutral/negative/positive)	N/A	`set*Button`	`null`
Icons	N/A	`set*ButtonIcon`	`null`

For specific button attributes, see the Buttons documentation.

Scrim attributes

Element	Attribute	Related methods	Default value
Dim ammount	`android:backgroundDimAmount`	N/A	32%

Theme overlays

Element	Theme overlay
Default theme overlay	`ThemeOverlay.MaterialComponents.MaterialAlertDialog`
Centered theme overlay	`ThemeOverlay.MaterialComponents.MaterialAlertDialog.Centered`

Default theme overlay attribute: ?attr/materialAlertDialogTheme

Theme attributes

Element	Theme attribute	Default 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:

MaterialAlertDialogBuilder
- Class description
- Class source

The following example shows a dialog with Material Theming.

Implementing dialog theming

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

In res/values/themes.xml:

<style name="Theme.App" parent="Theme.MaterialComponents.*">
  ...
  <item name="materialAlertDialogTheme">@style/ThemeOverlay.App.MaterialAlertDialog</item>
</style>

<style name="ThemeOverlay.App.MaterialAlertDialog" parent="ThemeOverlay.MaterialComponents.MaterialAlertDialog">
    <item name="colorPrimary">@color/shrine_pink_100</item>
    <item name="colorSecondary">@color/shrine_pink_100</item>
    <item name="colorSurface">@color/shrine_pink_light</item>
    <item name="colorOnSurface">@color/shrine_pink_900</item>
    <item name="alertDialogStyle">@style/MaterialAlertDialog.App</item>
    <item name="materialAlertDialogTitleTextStyle">@style/MaterialAlertDialog.App.Title.Text</item>
    <item name="buttonBarPositiveButtonStyle">@style/Widget.App.Button</item>
    <item name="buttonBarNeutralButtonStyle">@style/Widget.App.Button</item>
</style>

In res/values/styles.xml:

<style name="MaterialAlertDialog.App" parent="MaterialAlertDialog.MaterialComponents">
    <item name="shapeAppearance">@style/ShapeAppearance.App.MediumComponent</item>
</style>

<style name="MaterialAlertDialog.App.Title.Text" parent="MaterialAlertDialog.MaterialComponents.Title.Text">
     <item name="android:textColor">@color/shrine_pink_900</item>
</style>

<style name="Widget.App.Button" parent="Widget.MaterialComponents.Button.TextButton.Dialog">
    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Button.TextButton</item>
    <item name="shapeAppearance">@style/ShapeAppearance.App.SmallComponent</item>
</style>

<style name="ThemeOverlay.App.Button" parent="">
    <item name="colorPrimary">@color/shrine_pink_900</item>
</style>

<style name="ShapeAppearance.App.MediumComponent" parent="ShapeAppearance.MaterialComponents.MediumComponent">
    <item name="cornerFamily">cut</item>
    <item name="cornerSize">8dp</item>
</style>

<style name="ShapeAppearance.App.SmallComponent" parent="ShapeAppearance.MaterialComponents.SmallComponent">
    <item name="cornerFamily">cut</item>
    <item name="cornerSize">4dp</item>
</style>

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

MaterialAlertDialogBuilder(context,  R.style.ThemeOverlay_App_MaterialAlertDialog)
        ...
        .show()

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Dialog.md

Dialog.md

Dialogs

Using dialogs

Making dialogs accessible

Types

Dialogs

Dialog examples

Alert dialog

Simple dialog

Confirmation dialog

Full-screen dialog

Anatomy and key properties

Container attributes

Title attributes

Content attributes

Buttons attributes

Scrim attributes

Theme overlays

Theme attributes

Theming dialogs

Dialog theming example

Implementing dialog theming

Files

Dialog.md

Latest commit

History

Dialog.md

File metadata and controls

Dialogs

Using dialogs

Making dialogs accessible

Types

Dialogs

Dialog examples

Alert dialog

Simple dialog

Confirmation dialog

Full-screen dialog

Anatomy and key properties

Container attributes

Title attributes

Content attributes

Buttons attributes

Scrim attributes

Theme overlays

Theme attributes

Theming dialogs

Dialog theming example

Implementing dialog theming