In Android navigation, the term dialog destination refers to destinations within the app's navigation graph which take the form of dialog windows, overlaying app UI elements and content.
Because dialog destinations appear over hosted destinations that fill the
navigation host, there are some important considerations regarding how dialog
destinations interact with your NavController
's back stack.
Dialog composable
To create a dialog destination in Compose, add a destination to your NavHost
using the dialog()
function. The function behaves essentially the same as
composable
, only it creates a dialog destination rather than a hosted
destination.
Consider the following example:
@Serializable
object Home
@Serializable
object Settings
@Composable
fun HomeScreen(onNavigateToSettings: () -> Unit){
Column {
Text("Home")
Button(onClick = onNavigateToSettings){
Text("Open settings")
}
}
}
// This screen will be displayed as a dialog
@Composable
fun SettingsScreen(){
Text("Settings")
// ...
}
@Composable
fun MyApp() {
val navController = rememberNavController()
NavHost(navController, startDestination = Home) {
composable<Home> { HomeScreen(onNavigateToSettings = { navController.navigate(route = Settings) }) }
dialog<Settings> { SettingsScreen() }
}
}
- The start destination uses the
Home
route. Becausecomposable()
adds it to the graph, it is a hosted destination. - The other destination uses the
Settings
route.- Similarly, because
dialog()
adds it to the graph, it is a dialog destination. - When the user navigates from
HomeScreen
toSettingsScreen
the latter appears overHomeScreen
.
- Similarly, because
- Although
SettingsScreen
doesn't include aDialog
composable itself, because it is a dialog destination, theNavHost
displays it within aDialog
.
Dialog destinations appear over the previous destination in the NavHost
. Use
them when the dialog represents a separate screen in your app that needs its own
lifecycle and saved state, independent of any other destination in your
navigation graph. You might prefer to use an AlertDialog
or related
composable if you want a dialog for a less complex prompt, such as a
confirmation.
Kotlin DSL
If you are working with fragments and you are using the Kotlin DSL to create your graph, adding a dialog destination is very similar to when using Compose.
Consider how in the following snippet also uses the dialog()
function to
add a dialog destination that uses a fragment:
// Define destinations with serializable classes or objects
@Serializable
object Home
@Serializable
object Settings
// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
startDestination = Home
) {
// Associate the home route with the HomeFragment.
fragment<HomeFragment, Home> {
label = "Home"
}
// Define the settings destination as a dialog using DialogFragment.
dialog<SettingsFragment, Settings> {
label = "Settings"
}
}
XML
If you have an existing DialogFragment
, use the <dialog>
element to
add the dialog to your navigation graph, as shown in the following example:
<?xml version="1.0" encoding="utf-8"?> <navigation xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" android:id="@+id/nav_graph"> ... <dialog android:id="@+id/my_dialog_fragment" android:name="androidx.navigation.myapp.MyDialogFragment"> <argument android:name="myarg" android:defaultValue="@null" /> <action android:id="@+id/myaction" app:destination="@+id/another_destination"/> </dialog> ... </navigation>