Dialogs

Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks. There are two variants of dialogs.

1. Basic dialog
2. Full-screen dialog

Note: Images use various dynamic color schemes.

Design & API documentation

• Material 3 (M3) spec
• API reference

Anatomy

Basic dialogs

1. Container
2. Icon (optional)
3. Headline
4. Supporting text
5. Divider (optional)
6. Button (label text)
7. Scrim

Full-screen dialogs

1. Container
2. Header
3. Icon (close affordance)
4. Header
5. Text button
6. Divider (optional)

More details on anatomy items in the component guidelines.

Key properties

Container attributes

Title attributes

Content attributes

Supporting text

List item

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

Buttons attributes

For specific button attributes, see the Buttons documentation.

Scrim attributes

Theme overlays

Theme attributes

For the full list, see styles, attributes, and theme overlays.

Variants of dialogs

Basic dialog

Basic dialogs interrupt users with urgent information, details, or actions. Common use cases for basic dialogs include alerts, quick selection, and confirmation.

The following example shows a basic 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()

Full-screen dialog

Full-screen dialogs fill the entire screen, containing actions that require a series of tasks to complete. One example is 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.

Code implementation

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.

Dialogs example

Dialogs provide important prompts in a user flow.

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.

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.

Customizing dialogs

Theming dialogs

Dialogs support the customization 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.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:

<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:

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