Skip to content

Dialogs

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

"Dialog to confirm settings centered in a screen"

Contents

Design and API Documentation

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.

kt
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.Material3.Title.Icon style or descendant.

Types

There are two types of dialogs: 1. Basic dialog, 2. Full-screen dialog

Examples of the two 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:

Basic dialog

The following example shows a basic dialog.

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

In code:

kt
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()

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. Icon (optional)
  3. Title (optional)
  4. Content
  5. Buttons (optional)
  6. Scrim

Container attributes

ElementAttributeRelated methodsDefault value
Colorapp:backgroundTintN/A?attr/colorSurfaceContainerHigh
Shapeapp:shapeAppearance
app:shapeAppearanceOverlay
N/A?attr/shapeAppearanceCornerExtraLarge
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
Typographyandroid:textAppearanceN/A?attr/textAppearanceHeadlineSmall
IconN/AsetIcon
setIconAttribute
null
Icon tintapp:tintN/A?attr/colorSecondary

Content attributes

Supporting text

ElementAttributeRelated methodsDefault value
TextN/AsetMessagenull
Colorandroid:textColorN/A?attr/colorOnSurfaceVariant
Typographyandroid:textAppearanceN/A?attr/textAppearanceBodyMedium

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/colorOnSurfaceVariant
List item typographyandroid:textAppearanceN/A?attr/textAppearanceBodyMedium
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.Material3.CheckedTextView
Multi/single choice item text colorandroid:textColorN/A?attr/colorOnSurfaceVariant
Multi/single choice item typographyandroid:textAppearanceN/A?attr/textAppearanceBodyLarge

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

Buttons attributes

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

For specific button attributes, see the Buttons documentation.

Scrim attributes

ElementAttributeRelated methodsDefault value
Dim amountandroid:backgroundDimAmountN/A32%

Theme overlays

ElementTheme overlayDescription
Default theme overlayThemeOverlay.Material3.MaterialAlertDialogDialogs have start-aligned icons and titles with end-aligned buttons
Centered theme overlayThemeOverlay.Material3.MaterialAlertDialog.CenteredDialogs have center-aligned icons and titles with end-aligned buttons

Default theme overlay attribute: ?attr/materialAlertDialogTheme

Theme attributes

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

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

Theming dialogs

A dialog supports Material Theming which can customize 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:

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

<style name="ThemeOverlay.App.MaterialAlertDialog" parent="ThemeOverlay.Material3.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="buttonBarNegativeButtonStyle">@style/Widget.App.Button</item>
</style>

In res/values/styles.xml:

xml
<style name="MaterialAlertDialog.App" parent="MaterialAlertDialog.Material3">
    <item name="shapeAppearance">@style/ShapeAppearance.App.MediumComponent</item>
    <item name="shapeAppearanceOverlay">@null</item>
</style>

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

  <style name="Widget.App.Button" parent="Widget.Material3.Button.TextButton.Dialog">
    <item name="android:textColor">@color/shrine_pink_900</item>
  </style>

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

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

kt
MaterialAlertDialogBuilder(context,  R.style.ThemeOverlay_App_MaterialAlertDialog)
        ...
        .show()
Dialogs has loaded