# Dialogs
[Dialogs](https://m3.material.io/components/dialogs/overview) 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](https://m3.material.io/components/dialogs/overview)
* [API reference](https://developer.android.com/reference/com/google/android/material/dialog/package-summary)
## 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](https://m3.material.io/components/dialogs/guidelines#1e33c6d0-c56d-4c6f-a424-a742f452968d).
## Key properties
### 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`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_item.xml)
**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`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_multichoice.xml)
**Single choice item layout** | `app:singleChoiceItemLayout` | `setSingleChoiceItems` | [`@layout/mtrl_alert_select_dialog_singlechoice`](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/layout/mtrl_alert_select_dialog_singlechoice.xml)
**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](https://github.com/material-components/material-components-android/tree/master/docs/components/Button.md).
### Scrim attributes
Element | Attribute | Related methods | Default value
-------------- | ----------------------------- | --------------- | -------------
**Dim amount** | `android:backgroundDimAmount` | N/A | 32%
### Theme overlays
Element | Theme overlay | Description | Attribute
-------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- | ---------
**Default theme overlay** | `ThemeOverlay.Material3.MaterialAlertDialog` | Dialogs have start-aligned icons and titles with end-aligned buttons | `?attr/materialAlertDialogTheme`
**Centered theme overlay** | `ThemeOverlay.Material3.MaterialAlertDialog.Centered` | Dialogs have center-aligned icons and titles with end-aligned buttons | NA
### 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`
For the full list, see
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/styles.xml),
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/attrs.xml),
and
[theme overlays](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/res/values/themes.xml).
## 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:
```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 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`](https://developer.android.com/reference/androidx/fragment/app/DialogFragment)
as explained in the
[Android Developer guides](https://developer.android.com/guide/topics/ui/dialogs#FullscreenDialog).
## 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](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
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.
```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.
## Customizing dialogs
### Theming dialogs
Dialogs support the customization of color, typography, and shape.
#### Dialog theming example
API and source code:
* `MaterialAlertDialogBuilder`
* [Class description](https://developer.android.com/reference/com/google/android/material/dialog/MaterialAlertDialogBuilder)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/dialog/MaterialAlertDialogBuilder.java)
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`:
```xml
```
In `res/values/styles.xml`:
```xml
```
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()
```