Dialog.md

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

Element	Attribute	Related methods	Default value
Color	app:backgroundTint	N/A	?attr/colorSurfaceContainerHigh
Shape	app:shapeAppearance app:shapeAppearanceOverlay	N/A	?attr/shapeAppearanceCornerExtraLarge
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
Typography	android:textAppearance	N/A	?attr/textAppearanceHeadlineSmall
Icon	N/A	setIcon setIconAttribute	null
Icon tint	app:tint	N/A	?attr/colorSecondary

Content attributes

Supporting text

Element	Attribute	Related methods	Default value
Text	N/A	setMessage	null
Color	android:textColor	N/A	?attr/colorOnSurfaceVariant
Typography	android:textAppearance	N/A	?attr/textAppearanceBodyMedium

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/colorOnSurfaceVariant
List item typography	android:textAppearance	N/A	?attr/textAppearanceBodyMedium
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.Material3.CheckedTextView
Multi/single choice item text color	android:textColor	N/A	?attr/colorOnSurfaceVariant
Multi/single choice item typography	android:textAppearance	N/A	?attr/textAppearanceBodyLarge

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

Buttons attributes

Element	Attribute	Related methods	Default value
Buttons theme attributes (negative/positive)	app:buttonBar*ButtonStyle	N/A	@style/Widget.Material3.Button.TextButton.Dialog
Buttons theme attributes (neutral)	app:buttonBarNeutralButtonStyle	N/A	@style/Widget.Material3.Button.TextButton.Dialog.Flush
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 amount	android:backgroundDimAmount	N/A	32%

Theme overlays

Element	Theme overlay	Description
Default theme overlay	ThemeOverlay.Material3.MaterialAlertDialog	Dialogs have start-aligned icons and titles with end-aligned buttons
Centered theme overlay	ThemeOverlay.Material3.MaterialAlertDialog.Centered	Dialogs have center-aligned icons and titles with end-aligned buttons

Default theme overlay attribute: ?attr/materialAlertDialogTheme

Theme attributes

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

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