Jetpack Navigation 3
Priority: P1 (HIGH)
Guide for implementing and migrating to Navigation 3 in Jetpack Compose.
Core concepts
Navigation 3 replaces the previous NavHost/NavController pattern with a simpler, state-driven approach:
- Routes are Kotlin data objects/classes (not strings).
- Back stack is a plain
mutableStateListOf<Any>. NavDisplayrenders the current route based on a lambda.
Basic usage
kotlinval backStack = remember { mutableStateListOf<Any>(RouteHome) } NavDisplay( backStack = backStack, onBack = { backStack.removeLastOrNull() }, entryProvider = { key -> when (key) { is RouteHome -> NavEntry(key) { HomeScreen(onNavigate = { backStack.add(it) }) } is RouteDetail -> NavEntry(key) { DetailScreen(key.id) } else -> error("Unknown route: $key") } } )
Migration from Navigation 2
See migration guide for step-by-step conversion from NavHost/NavController to NavDisplay.
Key changes:
- Replace string routes with data objects/classes.
- Replace
NavHostwithNavDisplay. - Replace
NavController.navigate()with direct list manipulation. - Replace
navArgumentwith data class properties.
Common patterns
See recipes for code examples:
- Basic navigation with arguments
- Bottom navigation with multiple backstacks
- Deep links (basic and with synthetic backstack)
- Dialogs and bottom sheets
- Conditional navigation (auth flows)
- Returning results between screens
- Modularized navigation with Hilt or Koin
Verification
- Routes are data objects/classes, no string-based routing.
- Back stack is a
mutableStateListOf<Any>. -
NavDisplayhandles all routes inentryProvider. -
./gradlew buildsucceeds.
Anti-Patterns
- No string-based routes: Use Kotlin data objects/classes for type safety.
- No NavController for new projects: Use
NavDisplaywith a state list. - No
remember { navController() }: Navigation 3 doesn't use NavController.

