Display pop-up messages or requests for user input
Stay organized with collections
Save and categorize content based on your preferences.
The Dialog component displays pop-up messages or requests user input on a
layer above the main app content. It creates an interruptive UI experience to
capture user attention.
Among the use cases for a dialog are the following:
Confirming user action, such as when deleting a file.
Requesting user input, such as in a to-do list app.
Presenting a list of options for user selection, like choosing a country in
a profile setup.
This topic provides the following implementations:
This implementation requires that your project minSDK be set to API level 21 or
higher.
Dependencies
Create an Alert dialog
The AlertDialog composable provides a convenient API for creating a
Material Design themed dialog. The following example implements two buttons in
an alert dialog, one that dismisses the dialog, and another that confirms its
request:
This implementation implies a parent composable that passes arguments to the
child composable in this way:
Results
Figure 1. An alert dialog with buttons.
Key points
AlertDialog has specific parameters for handling particular elements of the
dialog. Among them are the following:
title: The text that appears along the top of the dialog.
text: The text that appears centered within the dialog.
icon: The graphic that appears at the top of the dialog.
onDismissRequest: The function called when the user dismisses the dialog,
such as by tapping outside of it.
dismissButton: A composable that serves as the dismiss button.
confirmButton: A composable that serves as the confirm button.
When the user clicks either of the buttons, the dialog closes. When the user
clicks confirm, it calls a function that also handles the confirmation. In
this example, those functions are onDismissRequest() and
onConfirmRequest().
In cases where your dialog requires a more complex set of buttons, you may
benefit from using the Dialog composable and populating it in a more
freeform manner.
Create a dialog
Dialog is a basic composable that doesn't provide any styling or
predefined slots for content. It is a straightforward container that you should
populate with a container such as Card. The following are some of the key
parameters of a dialog:
onDismissRequest: The lambda called when the user closes the dialog.
properties: An instance of DialogProperties that provides some
additional scope for customization.
Create a basic dialog
The following example is a basic implementation of the Dialog composable. Note
that it uses a Card as the secondary container. Without the Card, the Text
component would appear alone above the main app content.
Result
Note that when the dialog is open, the main app content beneath it appears
darkened and grayed out:
Figure 2. Minimal dialog.
Create an advanced dialog
The following is a more advanced implemented of the Dialog composable. In this
case, the component manually implements a similar interface to the preceding
AlertDialog example.
Result
Figure 3. A dialog that includes an image.
Collections that contain this guide
This guide is part of these curated Quick Guide collections that cover
broader Android development goals:
Display text
Text is a central piece of any UI. Find out different ways
you can present text in your app to provide a delightful user experience.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-08-26 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[],[],null,["\u003cbr /\u003e\n\nThe [`Dialog`](/reference/kotlin/androidx/compose/ui/window/package-summary#Dialog(kotlin.Function0,androidx.compose.ui.window.DialogProperties,kotlin.Function0)) component displays pop-up messages or requests user input on a\nlayer above the main app content. It creates an interruptive UI experience to\ncapture user attention.\n\nAmong the use cases for a dialog are the following:\n\n- Confirming user action, such as when deleting a file.\n- Requesting user input, such as in a to-do list app.\n- Presenting a list of options for user selection, like choosing a country in a profile setup.\n\nThis topic provides the following implementations:\n\n- [Alert](#alert)\n- [Basic dialog](#basic)\n- [Advanced dialog](#advanced)\n\nVersion compatibility\n\nThis implementation requires that your project minSDK be set to API level 21 or\nhigher.\n\nDependencies\n\nCreate an Alert dialog\n\nThe [`AlertDialog`](/reference/kotlin/androidx/compose/material3/package-summary#AlertDialog(kotlin.Function0,kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.ui.unit.Dp,androidx.compose.ui.window.DialogProperties)) composable provides a convenient API for creating a\nMaterial Design themed dialog. The following example implements two buttons in\nan alert dialog, one that dismisses the dialog, and another that confirms its\nrequest:\n\nThis implementation implies a parent composable that passes arguments to the\nchild composable in this way:\n\nResults **Figure 1.** An alert dialog with buttons.\n\nKey points\n\n`AlertDialog` has specific parameters for handling particular elements of the\ndialog. Among them are the following:\n\n- `title`: The text that appears along the top of the dialog.\n- `text`: The text that appears centered within the dialog.\n- `icon`: The graphic that appears at the top of the dialog.\n- `onDismissRequest`: The function called when the user dismisses the dialog, such as by tapping outside of it.\n- `dismissButton`: A composable that serves as the dismiss button.\n- `confirmButton`: A composable that serves as the confirm button.\n\n- When the user clicks either of the buttons, the dialog closes. When the user\n clicks confirm, it calls a function that also handles the confirmation. In\n this example, those functions are `onDismissRequest()` and\n `onConfirmRequest()`.\n\n In cases where your dialog requires a more complex set of buttons, you may\n benefit from using the `Dialog` composable and populating it in a more\n freeform manner.\n\nCreate a dialog\n\n[`Dialog`](/reference/kotlin/androidx/compose/ui/window/package-summary#Dialog(kotlin.Function0,androidx.compose.ui.window.DialogProperties,kotlin.Function0)) is a basic composable that doesn't provide any styling or\npredefined slots for content. It is a straightforward container that you should\npopulate with a container such as `Card`. The following are some of the key\nparameters of a dialog:\n\n- **`onDismissRequest`**: The lambda called when the user closes the dialog.\n- **`properties`** : An instance of [`DialogProperties`](/reference/kotlin/androidx/compose/ui/window/DialogProperties) that provides some additional scope for customization.\n\n| **Caution:** You must manually specify the size and shape of `Dialog`. You also must provide an inner container.\n\nCreate a basic dialog\n\nThe following example is a basic implementation of the `Dialog` composable. Note\nthat it uses a `Card` as the secondary container. Without the `Card`, the `Text`\ncomponent would appear alone above the main app content.\n\nResult\n\nNote that when the dialog is open, the main app content beneath it appears\ndarkened and grayed out:\n**Figure 2.** Minimal dialog.\n\nCreate an advanced dialog\n\nThe following is a more advanced implemented of the `Dialog` composable. In this\ncase, the component manually implements a similar interface to the preceding\n`AlertDialog` example.\n| **Caution:** If you only need to display a two-button dialog as in this example, you should use `AlertDialog` and its more convenient API. However, if you want to create a more complex dialog, perhaps with forms and multiple buttons, you should use `Dialog` with custom content, as in the following example.\n\nResult **Figure 3.** A dialog that includes an image.\n\nCollections that contain this guide\n\nThis guide is part of these curated Quick Guide collections that cover\nbroader Android development goals: \n\nDisplay text \nText is a central piece of any UI. Find out different ways you can present text in your app to provide a delightful user experience. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/display-text) \n\nRequest user input \nLearn how to implement ways for users to interact with your app by entering text and using other means of input. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/request-user-input) \n\nDisplay interactive components \nLearn how composable functions can enable you to easily create beautiful UI components based on the Material Design design system. \n[Quick guide collection](/develop/ui/compose/quick-guides/collections/display-interactive-components) \n\nHave questions or feedback \nGo to our frequently asked questions page and learn about quick guides or reach out and let us know your thoughts. \n[Go to FAQ](/quick-guides/faq) [Leave feedback](https://issuetracker.google.com/issues/new?component=1573691&template=1993320)"]]