Dialogs ​

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

Contents

• Design and API Documentation
• Using dialogs
• Basic dialog
• Full-screen dialog
• Theming

Design and API Documentation ​

• Google Material3 Spec
• API reference

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

Types ​

There are two types of dialogs: 1. Basic dialog, 2. 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

Basic dialog ​

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

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

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 ​

Default theme overlay attribute: ?attr/materialAlertDialogTheme

Theme attributes ​

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:

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