Nav3 Router: Convenient Navigation on Top of Jetpack Navigation 3

What is Jetpack Navigation 3? Jetpack Navigation 3 is a new Google navigation library that is fundamentally different from previous versions. The main idea of Nav3 is simple: you have a NavBackStack — a regular mutable list where each element represents a screen in your application. NavBackStack You add and remove elements from this list, and the UI automatically updates. Each screen is represented as a NavKey — a regular Kotlin class. NavKey This gives you full control over navigation, but requires writing quite a lot of boilerplate code for typical operations. Why Working Directly with NavBackStack is Inconvenient Let's look at what the code looks like when working directly with NavBackStack: NavBackStack @Composable fun MyApp() { val backStack = rememberNavBackStack(Screen.Home) // Add a screen backStack.add(Screen.Details("123")) // Go back backStack.removeLastOrNull() // Replace current screen backStack.set(backStack.lastIndex, Screen.Success) } @Composable fun MyApp() { val backStack = rememberNavBackStack(Screen.Home) // Add a screen backStack.add(Screen.Details("123")) // Go back backStack.removeLastOrNull() // Replace current screen backStack.set(backStack.lastIndex, Screen.Success) } Problems begin when you need to trigger navigation from a ViewModel. You'll have to either pass NavBackStack to the ViewModel (which, in my understanding, violates architectural principles, as I believe the ViewModel shouldn't know about Compose-specific things), or create intermediate callbacks for each navigation action. NavBackStack Additionally, when working with the stack directly, it's easy to forget to handle edge cases. How Nav3 Router Simplifies the Work Nav3 Router is a thin wrapper over Navigation 3 that provides a familiar API for navigation. Instead of thinking about indices and list operations, you simply say "go to screen X" or "go back." Important point: Nav3 Router doesn't create its own stack. It works with the same NavBackStack that Navigation 3 provides, just making it more convenient to work with. When you call router.push(Screen.Details), the library translates this into the corresponding operation with the original stack. NavBackStack router.push(Screen.Details) Main advantages: Can be used from ViewModel Navigation commands are buffered if UI is temporarily unavailable (for example, during screen rotation) All stack operations happen atomically Clear API Flexibility in modification and adding custom behavior Can be used from ViewModel Navigation commands are buffered if UI is temporarily unavailable (for example, during screen rotation) All stack operations happen atomically Clear API Flexibility in modification and adding custom behavior Installation Nav3 Router is available on Maven Central. Add the dependency to your build.gradle.kts: build.gradle.kts // For shared module in KMP project kotlin { sourceSets { commonMain.dependencies { implementation("io.github.arttttt.nav3router:nav3router:1.0.0") } } } // For Android-only project dependencies { implementation("io.github.arttttt.nav3router:nav3router:1.0.0") } // For shared module in KMP project kotlin { sourceSets { commonMain.dependencies { implementation("io.github.arttttt.nav3router:nav3router:1.0.0") } } } // For Android-only project dependencies { implementation("io.github.arttttt.nav3router:nav3router:1.0.0") } The library source code is available on GitHub: github.com/arttttt/Nav3Router github.com/arttttt/Nav3Router How Nav3 Router is Structured The library consists of three main parts, each solving its own task: Router — Developer Interface Router provides methods like push(), pop(), replace(). When you call these methods, Router creates corresponding commands and sends them down the chain. Router itself knows nothing about how navigation will be executed — this allows using it from anywhere. push() pop() replace() CommandQueue — Buffer Between Commands and Their Execution CommandQueue solves the timing problem. Imagine: the user pressed a button during screen rotation. The UI is being recreated, and the navigator is temporarily unavailable. CommandQueue will save the command and execute it as soon as the navigator is ready again. Without this, the command would simply be lost. // Simplified queue logic class CommandQueue { private var navigator: Navigator ? = null private val pending = mutableListOf >() fun executeCommand(command: Command ) { if (navigator != null) { navigator.apply(command) // Navigator exists - execute immediately } else { pending.add(command) // No - save for later } } } // Simplified queue logic class CommandQueue { private var navigator: Navigator ? = null private val pending = mutableListOf >() fun executeCommand(command: Command ) { if (navigator != null) { navigator.apply(command) // Navigator exists - execute immediately } else { pending.add(command) // No - save for later } } } Navigator — The One Who Works with the Stack Navigator takes commands and applies them to NavBackStack. Important detail: it first creates a copy of the current stack, applies all commands to it, and only then atomically replaces the original stack with the modified copy. This guarantees that the UI will never see intermediate stack states. NavBackStack // Simplified Navigator logic fun applyCommands(commands: Array ) { val stackCopy = backStack.toMutableList() // Work with a copy for (command in commands) { when (command) { is Push -> stackCopy.add(command.screen) is Pop -> stackCopy.removeLastOrNull() // ... other commands } } backStack.swap(stackCopy) // Atomically apply changes } // Simplified Navigator logic fun applyCommands(commands: Array ) { val stackCopy = backStack.toMutableList() // Work with a copy for (command in commands) { when (command) { is Push -> stackCopy.add(command.screen) is Pop -> stackCopy.removeLastOrNull() // ... other commands } } backStack.swap(stackCopy) // Atomically apply changes } Getting Started With Nav3 Router The simplest way — don't even create Router manually. Nav3Host will do it for you: @Composable fun App() { val backStack = rememberNavBackStack(Screen.Home) // Nav3Host will create Router automatically Nav3Host(backStack = backStack) { backStack, onBack, router -> NavDisplay( backStack = backStack, onBack = onBack, entryProvider = entryProvider { entry { HomeScreen( onOpenDetails = { router.push(Screen.Details) // Use router } ) } entry { DetailsScreen( onBack = { router.pop() } ) } } ) } } @Composable fun App() { val backStack = rememberNavBackStack(Screen.Home) // Nav3Host will create Router automatically Nav3Host(backStack = backStack) { backStack, onBack, router -> NavDisplay( backStack = backStack, onBack = onBack, entryProvider = entryProvider { entry { HomeScreen( onOpenDetails = { router.push(Screen.Details) // Use router } ) } entry { DetailsScreen( onBack = { router.pop() } ) } } ) } } For more complex applications, it makes sense to create a Router through DI and pass it to the ViewModel: Define screens @Serializable sealed interface Screen : NavKey { @Serializable data object Home : Screen @Serializable data class Product(val id: String) : Screen @Serializable data object Cart : Screen } @Serializable sealed interface Screen : NavKey { @Serializable data object Home : Screen @Serializable data class Product(val id: String) : Screen @Serializable data object Cart : Screen } Pass router to Nav3Host. @Composable fun App() { val backStack = rememberNavBackStack(Screen.Home) val router: Router = getSomehowUsingDI() // Pass Router to Nav3Host Nav3Host( backStack = backStack, router = router, ) { backStack, onBack, _ -> NavDisplay( backStack = backStack, onBack = onBack, entryProvider = entryProvider { entry { HomeScreen() } entry { DetailsScreen() } } ) } } @Composable fun App() { val backStack = rememberNavBackStack(Screen.Home) val router: Router = getSomehowUsingDI() // Pass Router to Nav3Host Nav3Host( backStack = backStack, router = router, ) { backStack, onBack, _ -> NavDisplay( backStack = backStack, onBack = onBack, entryProvider = entryProvider { entry { HomeScreen() } entry { DetailsScreen() } } ) } } ViewModel receives Router through constructor. class ProductViewModel( private val router: Router , private val cartRepository: CartRepository ) : ViewModel() { fun addToCart(productId: String) { viewModelScope.launch { cartRepository.add(productId) router.push(Screen.Cart) // Navigation from ViewModel } } } class ProductViewModel( private val router: Router , private val cartRepository: CartRepository ) : ViewModel() { fun addToCart(productId: String) { viewModelScope.launch { cartRepository.add(productId) router.push(Screen.Cart) // Navigation from ViewModel } } } In UI, just use ViewModel. @Composable fun ProductScreen(viewModel: ProductViewModel = koinViewModel()) { Button(onClick = { viewModel.addToCart(productId) }) { Text("Add to Cart") } } @Composable fun ProductScreen(viewModel: ProductViewModel = koinViewModel()) { Button(onClick = { viewModel.addToCart(productId) }) { Text("Add to Cart") } } Examples of Typical Scenarios Simple Forward-Back Navigation // Navigate to a new screen router.push(Screen.Details(productId)) // Go back router.pop() // Navigate with replacement of current screen (can't go back) router.replaceCurrent(Screen.Success) // Navigate to a new screen router.push(Screen.Details(productId)) // Go back router.pop() // Navigate with replacement of current screen (can't go back) router.replaceCurrent(Screen.Success) Working with Screen Chains // Open multiple screens at once router.push( Screen.Category("electronics"), Screen.Product("laptop-123"), Screen.Reviews("laptop-123") ) // Return to a specific screen // Will remove all screens above Product from the stack router.popTo(Screen.Product("laptop-123")) // Open multiple screens at once router.push( Screen.Category("electronics"), Screen.Product("laptop-123"), Screen.Reviews("laptop-123") ) // Return to a specific screen // Will remove all screens above Product from the stack router.popTo(Screen.Product("laptop-123")) Checkout Scenario @Composable fun CheckoutScreen(router: Router ) { Button( onClick = { // After checkout we need to: // 1. Show confirmation screen // 2. Prevent going back to cart router.replaceStack( Screen.Home, Screen.OrderSuccess(orderId) ) // Now only Home and OrderSuccess are in the stack } ) { Text("Place Order") } } @Composable fun CheckoutScreen(router: Router ) { Button( onClick = { // After checkout we need to: // 1. Show confirmation screen // 2. Prevent going back to cart router.replaceStack( Screen.Home, Screen.OrderSuccess(orderId) ) // Now only Home and OrderSuccess are in the stack } ) { Text("Place Order") } } Exiting Nested Navigation // User is deep in settings: // Home -> Settings -> Account -> Privacy -> DataManagement // "Done" button should return to home Button( onClick = { // Will leave only root (Home) router.clearStack() } ) { Text("Done") } // Or if you need to close the app from anywhere Button( onClick = { // Will leave only current screen and trigger system back router.dropStack() } ) { Text("Exit") } // User is deep in settings: // Home -> Settings -> Account -> Privacy -> DataManagement // "Done" button should return to home Button( onClick = { // Will leave only root (Home) router.clearStack() } ) { Text("Done") } // Or if you need to close the app from anywhere Button( onClick = { // Will leave only current screen and trigger system back router.dropStack() } ) { Text("Exit") } Bonus: SceneStrategy and Dialogs So far, we've only talked about simple navigation between screens. But what if you need to show a dialog or bottom sheet? This is where the SceneStrategy concept from Navigation 3 comes to help. What is SceneStrategy? SceneStrategy is a mechanism that determines exactly how screens from your stack will be displayed. By default, Navigation 3 uses SinglePaneSceneStrategy, which simply shows the last screen from the stack. But you can create your own strategies for more complex scenarios. SinglePaneSceneStrategy Think of SceneStrategy as a director who looks at your stack of screens and decides: "Okay, these three screens we show normally, but this last one — as a modal window on top of the previous ones". This allows representing different UI patterns with the same stack. Creating a Strategy for ModalBottomSheet Let's create a strategy that will show certain screens as bottom sheets. First, let's define how we'll mark such screens: @Serializable sealed interface Screen : NavKey { @Serializable data object Home : Screen @Serializable data class Product(val id: String) : Screen // This screen will be shown as bottom sheet @Serializable data object Filters : Screen } @Serializable sealed interface Screen : NavKey { @Serializable data object Home : Screen @Serializable data class Product(val id: String) : Screen // This screen will be shown as bottom sheet @Serializable data object Filters : Screen } Now, let's create the strategy itself. It will check the metadata of the last screen and, if it finds a special marker, show it as a bottom sheet: class BottomSheetSceneStrategy : SceneStrategy { companion object { // Metadata key by which we identify bottom sheet private const val BOTTOM_SHEET_KEY = "bottomsheet" // Helper function to create metadata fun bottomSheet(): Map { return mapOf(BOTTOM_SHEET_KEY to true) } } @Composable override fun calculateScene( entries: List >, onBack: (Int) -> Unit ): Scene ? { val lastEntry = entries.lastOrNull() ?: return null // Check if the last screen has bottom sheet marker val isBottomSheet = lastEntry.metadata[BOTTOM_SHEET_KEY] as? Boolean if (isBottomSheet == true) { // Return special Scene for bottom sheet return BottomSheetScene( entry = lastEntry, previousEntries = entries.dropLast(1), onBack = onBack ) } // This is not a bottom sheet, let another strategy handle it return null } } class BottomSheetSceneStrategy : SceneStrategy { companion object { // Metadata key by which we identify bottom sheet private const val BOTTOM_SHEET_KEY = "bottomsheet" // Helper function to create metadata fun bottomSheet(): Map { return mapOf(BOTTOM_SHEET_KEY to true) } } @Composable override fun calculateScene( entries: List >, onBack: (Int) -> Unit ): Scene ? { val lastEntry = entries.lastOrNull() ?: return null // Check if the last screen has bottom sheet marker val isBottomSheet = lastEntry.metadata[BOTTOM_SHEET_KEY] as? Boolean if (isBottomSheet == true) { // Return special Scene for bottom sheet return BottomSheetScene( entry = lastEntry, previousEntries = entries.dropLast(1), onBack = onBack ) } // This is not a bottom sheet, let another strategy handle it return null } } Combining Multiple Strategies In a real application, you might need bottom sheets, dialogs, and regular screens. For this, you can create a delegate strategy that will choose the right strategy for each screen: class DelegatedScreenStrategy ( private val strategyMap: Map >, private val fallbackStrategy: SceneStrategy ) : SceneStrategy { @Composable override fun calculateScene( entries: List >, onBack: (Int) -> Unit ): Scene ? { val lastEntry = entries.lastOrNull() ?: return null // Check all keys in metadata for (key in lastEntry.metadata.keys) { val strategy = strategyMap[key] if (strategy != null) { // Found suitable strategy return strategy.calculateScene(entries, onBack) } } // Use default strategy return fallbackStrategy.calculateScene(entries, onBack) } } class DelegatedScreenStrategy ( private val strategyMap: Map >, private val fallbackStrategy: SceneStrategy ) : SceneStrategy { @Composable override fun calculateScene( entries: List >, onBack: (Int) -> Unit ): Scene ? { val lastEntry = entries.lastOrNull() ?: return null // Check all keys in metadata for (key in lastEntry.metadata.keys) { val strategy = strategyMap[key] if (strategy != null) { // Found suitable strategy return strategy.calculateScene(entries, onBack) } } // Use default strategy return fallbackStrategy.calculateScene(entries, onBack) } } Using in Application Now, let's put it all together. Here's what using bottom sheet looks like in a real application: @Composable fun ShoppingApp() { val backStack = rememberNavBackStack(Screen.Home) val router = rememberRouter () Nav3Host( backStack = backStack, router = router ) { backStack, onBack, router -> NavDisplay( backStack = backStack, onBack = onBack, // Use our combined strategy sceneStrategy = DelegatedScreenStrategy( strategyMap = mapOf( "bottomsheet" to BottomSheetSceneStrategy(), "dialog" to DialogSceneStrategy() // Navigation 3 already has this strategy ), fallbackStrategy = SinglePaneSceneStrategy() // Regular screens ), entryProvider = entryProvider { entry { HomeScreen( onOpenFilters = { // Open filters as bottom sheet router.push(Screen.Filters) } ) } entry { screen -> ProductScreen(productId = screen.id) } // Specify that Filters should be bottom sheet entry ( metadata = BottomSheetSceneStrategy.bottomSheet() ) { FiltersContent( onApply = { filters -> // Apply filters and close bottom sheet applyFilters(filters) router.pop() } ) } } ) } } @Composable fun ShoppingApp() { val backStack = rememberNavBackStack(Screen.Home) val router = rememberRouter () Nav3Host( backStack = backStack, router = router ) { backStack, onBack, router -> NavDisplay( backStack = backStack, onBack = onBack, // Use our combined strategy sceneStrategy = DelegatedScreenStrategy( strategyMap = mapOf( "bottomsheet" to BottomSheetSceneStrategy(), "dialog" to DialogSceneStrategy() // Navigation 3 already has this strategy ), fallbackStrategy = SinglePaneSceneStrategy() // Regular screens ), entryProvider = entryProvider { entry { HomeScreen( onOpenFilters = { // Open filters as bottom sheet router.push(Screen.Filters) } ) } entry { screen -> ProductScreen(productId = screen.id) } // Specify that Filters should be bottom sheet entry ( metadata = BottomSheetSceneStrategy.bottomSheet() ) { FiltersContent( onApply = { filters -> // Apply filters and close bottom sheet applyFilters(filters) router.pop() } ) } } ) } } What's happening here? When you call router.push(Screen.Filters), the screen is added to the stack as usual. But thanks to metadata and our strategy, the UI understands that this screen needs to be shown as a bottom sheet on top of the previous screen, rather than replacing it completely. router.push(Screen.Filters) When calling router.pop() the bottom sheet will close, and you'll return to the previous screen. From Router's point of view, this is regular back navigation, but visually it looks like closing a modal window. router.pop() Advantages of This Approach Using SceneStrategy provides several important advantages. First, your navigation logic remains simple — you still use push and pop without thinking about how exactly the screen will be shown. Second, navigation state remains consistent — bottom sheet is just another screen in the stack that is properly saved during screen rotation or process kill. And finally, it provides great flexibility — you can easily change how a screen is displayed by just changing its metadata, without touching the navigation logic. push pop This approach is especially useful when the same screen can be shown differently depending on context. For example, a login screen can be a regular screen on first app launch and a modal dialog when attempting to perform an action that requires authorization. Why You Should Use Nav3 Router Nav3 Router doesn't try to replace Navigation 3 or add new features. Its task is to make working with navigation convenient and predictable. You get a simple API that can be used from any layer of the application, automatic handling of timing issues, and the ability to easily test navigation logic. At the same time, under the hood, regular Navigation 3 still works with all its capabilities: state saving, animation support, and proper handling of the system "Back" button. If you're already using Navigation 3 or planning to migrate to it, Nav3 Router will help make this experience more pleasant without adding unnecessary complexity to the project. Links GitHub repository: github.com/arttttt/Nav3Router Usage examples: see sample folder in the repository GitHub repository: github.com/arttttt/Nav3Router GitHub repository github.com/arttttt/Nav3Router Usage examples: see sample folder in the repository Usage examples sample