Nav3 Router

You can set up navigation in two ways:

Option A: Simple Setup

Use rememberNavBackStack and Nav3Host. The router is provided automatically within the Nav3Host lambda.

Option B: Dependency Injection (Recommended)

Inject a Router<Screen> instance from your DI container (like Koin or Hilt) and pass it to Nav3Host. This allows your ViewModels to use the same router instance.

@Composable
fun App() {
    // Option B: Using DI
    val router: Router<Screen> = koinInject()
    val backStack = rememberNavBackStack(Screen.Home)
    
    Nav3Host(
        backStack = backStack,
        router = router
    ) { backStack, onBack, _ ->
        NavDisplay(
            backStack = backStack,
            onBack = onBack,
            entryProvider = entryProvider {
                entry<Screen.Home> {
                    HomeScreen(onNavigateToDetails = { id -> router.push(Screen.Details(id)) })
                }
                // ... other entries
            }
        )
    }
}

Use the nav3-router-test artifact to test navigation logic in plain unit tests without Compose or Nav3Host.

Testing Stack State

Use router.bindForTest(scope) to get an observable back stack. You can then assert against the contents of the list.

Testing Command Emission

Use RecordingNavigator with router.bindForTest(recorder) to assert that specific commands (like Push, Pop, etc.) were emitted in the correct order.

Testing Result Handling

To test a screen awaiting a result, drive the producer side within your test using router.popWithResult(value).

@Test
fun `opens details`() = runTest {
    Dispatchers.setMain(StandardTestDispatcher(testScheduler))

    val router = Router<Screen>()
    val backStack = router.bindForTest(scope = backgroundScope)

    HomeViewModel(router).openDetails("42")
    advanceUntilIdle()

    assertEquals(Screen.Details("42"), backStack.last())

    Dispatchers.resetMain()
}

Nav3 Router allows passing typed results back to a caller. Results are addressed by their type and are stored in a saveable store, making them durable across configuration changes and process death.

1. Define a Serializable Result Type

@Serializable
data class SelectedColor(val argb: Long)

2. Producing a Result

From the child screen, use popWithResult(value) to return a value and pop, or sendResult(value) to return a value without popping.

// Inside a screen entry
ColorPickerScreen(onPick = { argb -> router.popWithResult(SelectedColor(argb)) })

3. Consuming a Result

Durable Consumption (Recommended)

Use registerForResult<T> in a ViewModel or DisposableEffect. This is the only method that survives process death because it re-attaches to the saveable store.

class HomeViewModel(private val router: Router<Screen>) : ViewModel() {
    private val pickColor = router.registerForResult<SelectedColor>(
        onResult = { selected -> /* handle result */ },
        onCancelled = { /* handle cancel */ }
    )

    fun pickColor() = router.push(Screen.ColorPicker)

    override fun onCleared() = pickColor.dispose()
}

Ephemeral Consumption

The following methods are convenient but do not survive process death (they are captured at the call site):

• pushForResult<T>(screen) { result -> ... }: One-call ergonomic form.
• openForResult<T> { screen }: A suspend function that returns the result or null.
• resultFlow<T>(): A cold Flow of results.

// Ephemeral example
@OptIn(EphemeralResultApi::class)
val selected: SelectedColor? = router.openForResult { Screen.ColorPicker }

The CommandQueue<T> class manages the queuing and execution of navigation commands. It is designed to solve timing issues where navigation commands are issued before the navigation system (the Navigator) is ready (e.g., during configuration changes).

Key Behaviors:

• Buffering: If no Navigator is currently registered, commands passed to executeCommands are stored in a pending queue.
• Automatic Execution: As soon as a Navigator is registered via setNavigator, all queued commands are immediately executed in the order they were received.
• Thread Safety: All command execution is automatically dispatched to the Main thread using a CoroutineScope, making executeCommands safe to call from any thread.
• Lifecycle: You can stop command execution by calling removeNavigator(), which causes subsequent commands to be queued until a new navigator is provided.

// Example of using CommandQueue to buffer commands until a navigator is ready
val commandQueue = CommandQueue<MyScreen>()

// This command will be queued because no navigator is set yet
commandQueue.executeCommands(arrayOf(NavigateToCommand(MyScreen.Home)))

// Later, when the navigator is initialized...
commandQueue.setNavigator(myNavigatorInstance)
// The Home navigation command is now automatically executed on the Main thread.