Navigation

Navigation in Compose

Compose navigation replaces the Activity-based navigation model with a composable-based approach. You define a graph of routes, and a NavHost renders the current route's composable.

Setup

Add the dependency:

dependencies {
    implementation("androidx.navigation:navigation-compose:2.7.6")
}

Defining Routes

Routes are strings that identify screens:

object Routes {
    const val HOME = "home"
    const val SEARCH = "search"
    const val PROFILE = "profile"
    const val DETAIL = "detail/{itemId}"
    const val SETTINGS = "settings"
}

Creating a NavHost

@Composable
fun AppNavigation() {
    val navController = rememberNavController()

    NavHost(
        navController = navController,
        startDestination = Routes.HOME
    ) {
        composable(Routes.HOME) {
            HomeScreen(
                onItemClick = { itemId ->
                    navController.navigate("detail/$itemId")
                }
            )
        }

        composable(Routes.SEARCH) {
            SearchScreen()
        }

        composable(
            route = Routes.DETAIL,
            arguments = listOf(navArgument("itemId") { type = NavType.StringType })
        ) { backStackEntry ->
            val itemId = backStackEntry.arguments?.getString("itemId") ?: return@composable
            DetailScreen(itemId = itemId)
        }

        composable(Routes.SETTINGS) {
            SettingsScreen()
        }
    }
}

Type-Safe Navigation (Kotlin Serialization)

Modern Compose Navigation supports serializable route classes:

@Serializable
object HomeRoute

@Serializable
object SearchRoute

@Serializable
data class DetailRoute(val itemId: String)

@Serializable
object SettingsRoute

Then define the graph:

NavHost(
    navController = navController,
    startDestination = HomeRoute
) {
    composable<HomeRoute> {
        HomeScreen()
    }
    composable<SearchRoute> {
        SearchScreen()
    }
    composable<DetailRoute> { backStackEntry ->
        val route = backStackEntry.toRoute<DetailRoute>()
        DetailScreen(itemId = route.itemId)
    }
}

Navigate with:

navController.navigate(DetailRoute(itemId = "123"))

This eliminates string-based route errors at compile time.

Passing Arguments

Arguments are part of the route string or passed via navArgument:

// String argument
composable(
    route = "detail/{itemId}",
    arguments = listOf(
        navArgument("itemId") {
            type = NavType.StringType
            nullable = false
        }
    )
) { backStackEntry ->
    val itemId = backStackEntry.arguments?.getString("itemId")
    DetailScreen(itemId = itemId ?: "")
}

// Navigate with argument
navController.navigate("detail/product_123")

Optional Arguments with Default Values

composable(
    route = "search?query={query}",
    arguments = listOf(
        navArgument("query") {
            type = NavType.StringType
            defaultValue = ""
        }
    )
) { backStackEntry ->
    val query = backStackEntry.arguments?.getString("query") ?: ""
    SearchScreen(initialQuery = query)
}

// Navigate without optional arg (uses default)
navController.navigate("search")

// Navigate with optional arg
navController.navigate("search?query=kotlin")

Deep Links

Deep links let your app respond to URLs:

composable(
    route = "detail/{itemId}",
    arguments = listOf(navArgument("itemId") { type = NavType.StringType }),
    deepLinks = listOf(
        navDeepLink {
            uriPattern = "myapp://item/{itemId}"
        }
    )
) { backStackEntry ->
    val itemId = backStackEntry.arguments?.getString("itemId")
    DetailScreen(itemId = itemId ?: "")
}

Register the intent filter in AndroidManifest.xml:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" android:host="item" />
</intent-filter>

Back Stack Management

// Navigate (adds to back stack)
navController.navigate("detail/123")

// Pop back to a specific destination
navController.popBackStack("home", inclusive = false)

// Pop up to start destination (clears back stack)
navController.popBackStack(navController.graph.startDestinationId, inclusive = false)

// Navigate and clear back stack
navController.navigate("home") {
    popUpTo(navController.graph.startDestinationId) {
        inclusive = true
    }
    launchSingleTop = true
}

The popUpTo with inclusive = true clears the entire back stack. launchSingleTop prevents duplicate screens.

Nested Navigation Graphs

For complex apps, group related screens into nested graphs:

NavHost(
    navController = navController,
    startDestination = "main"
) {
    // Main tab graph
    navigation(startDestination = Routes.HOME, route = "main") {
        composable(Routes.HOME) { HomeScreen() }
        composable(Routes.SEARCH) { SearchScreen() }
        composable(Routes.PROFILE) { ProfileScreen() }
    }

    // Detail flow
    composable(
        route = "detail/{itemId}",
        arguments = listOf(navArgument("itemId") { type = NavType.StringType })
    ) { backStackEntry ->
        val itemId = backStackEntry.arguments?.getString("itemId") ?: ""
        DetailScreen(
            itemId = itemId,
            onBack = { navController.popBackStack() }
        )
    }
}

Bottom Navigation with Navigation

@Composable
fun MainScreen() {
    val navController = rememberNavController()

    Scaffold(
        bottomBar = {
            NavigationBar {
                val navBackStackEntry by navController.currentBackStackEntryAsState()
                val currentRoute = navBackStackEntry?.destination?.route

                listOf(
                    "home" to Icons.Default.Home,
                    "search" to Icons.Default.Search,
                    "profile" to Icons.Default.Person
                ).forEach { (route, icon) ->
                    NavigationBarItem(
                        selected = currentRoute == route,
                        onClick = {
                            navController.navigate(route) {
                                popUpTo(navController.graph.findStartDestination().id) {
                                    saveState = true
                                }
                                launchSingleTop = true
                                restoreState = true
                            }
                        },
                        icon = { Icon(icon, contentDescription = route) },
                        label = { Text(route.replaceFirstChar { it.uppercase() }) }
                    )
                }
            }
        }
    ) { padding ->
        NavHost(
            navController = navController,
            startDestination = "home",
            modifier = Modifier.padding(padding)
        ) {
            composable("home") { HomeScreen() }
            composable("search") { SearchScreen() }
            composable("profile") { ProfileScreen() }
        }
    }
}

The key flags:

• popUpTo(startDestination) with saveState = true -- avoids stacking duplicate screens
• launchSingleTop = true -- prevents re-creating the same screen
• restoreState = true -- restores tab state when switching back