Navigation and routing

Navigation is a key part of UI applications that allows users to move between different application screens. Compose Multiplatform adopts the Jetpack Compose approach to navigation.

Setup

To use the navigation library, add the following dependency to your commonMain source set:

kotlin {
    // ...
    sourceSets {
        // ...
        commonMain.dependencies {
            // ...
            implementation("org.jetbrains.androidx.navigation:navigation-compose:2.8.0-alpha10")
        }
        // ...
    }
}

Minimal example

https://developer.android.com/guide/navigation/design#compose-minimal [The minimal example works with CMP, with the corresponding environment setup.]

Sample project

To see the Compose Multiplatform navigation library in action, check out the nav_cupcake project, which was converted from the Navigate between screens with Compose Android codelab.

Just as with Jetpack Compose, to implement navigation, you should:

List routes that should be included in the navigation graph. Each route must be a unique string that defines a path.
Create a NavHostController instance as your main composable property to manage navigation.
Add a NavHost composable to your app:
1. Choose the starting destination from the list of routes you defined earlier.
2. Create a navigation graph, either directly, as part of creating a NavHost, or programmatically, using the NavController.createGraph() function.

Each back stack entry (each navigation route included in the graph) implements the LifecycleOwner interface. A switch between different screens of the app makes it change its state from RESUMED to STARTED and back. RESUMED is also described as "settled": navigation is considered finished when the new screen is prepared and active. See the Lifecycle page for details of the current implementation in Compose Multiplatform.

Limitations

Current limitations of navigation in Compose Multiplatform, compared to Jetpack Compose:

Deep links (handling or following them) are not supported.
The BackHandler function and predictive back gestures are not supported on any platform besides Android.

Compose Multiplatform for web fully supports the common Navigation library APIs, and on top of that allows your apps to receive navigational input from the browser. Users can use the Back and Forward buttons in the browser to move between navigation routes reflected in the browser history, as well as use the address bar to understand where they are and get to a destination directly.

To bind the web app to the navigation graph defined in your common code, call the window.bindToNavigation() method in your Kotlin/Wasm or Kotlin/JS code:

@OptIn(ExperimentalComposeUiApi::class)
@ExperimentalBrowserHistoryApi
fun main() {
    val body = document.body ?: return

    ComposeViewport(body) {

        val navController = rememberNavController()
        // Assumes that your main composable function in common code is App()
        App(navController)
        LaunchedEffect(Unit) {
            window.bindToNavigation(navController)
        }
    }
}

After a window.bindToNavigation(navController) call:

The URL displayed in the browser reflects the current route (in the URL fragment, after the # character).
The app parses URLs entered manually to translate them into destinations within the app.

By default, when using type-safe navigation, a destination is translated into a URL fragment according to the kotlinx.serialization default with appended arguments: <app package>.<serializable type>/<argument1>/<argument2>. For example, example.org#org.example.app.StartScreen/123/Alice%2520Smith.

Customize translating routes into URLs and back

As Compose Multiplatform apps are single-page apps, the framework manipulates the address bar to imitate usual web navigation. If you would like to make your URLs more readable and isolate implementation from URL patterns, you can assign the name to a screen directly or develop fully custom processing for destination routes:

To simply make a URL readable, use the @SerialName annotation to explicitly set the serial name for a serializable object or class:
// Instead of using the app package and object name, // this route will be translated to the URL simply as "#start" @Serializable @SerialName("start") data object StartScreen
To fully construct every URL, you can use the optional getBackStackEntryRoute lambda.

Full URL customization

To implement a fully custom route to URL transformation:

Pass the optional getBackStackEntryRoute lambda to the window.bindToNavigation() function to specify how routes should be converted into URL fragments when necessary.
If needed, add code that catches URL fragments in the address bar (when someone clicks or pastes your app's URL) and translates URLs into routes to navigate users accordingly.

Here's an example of a simple type-safe navigation graph to use with the following samples of web code (commonMain/kotlin/org.example.app/App.kt):

// Serializable object and classes for route arguments in the navigation graph @Serializable data object StartScreen @Serializable data class Id(val id: Long) @Serializable data class Patient(val name: String, val age: Long) @Composable internal fun App( navController: NavHostController = rememberNavController() ) = AppTheme { NavHost( navController = navController, startDestination = StartScreen ) { composable<StartScreen> { Column( modifier = Modifier.fillMaxSize(), horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.Center ) { Text("Starting screen") // Button that opens the 'Id' screen with a suitable parameter Button(onClick = { navController.navigate(Id(222)) }) { Text("Pass 222 as a parameter to the ID screen") } // Button that opens the 'Patient' screen with suitable parameters Button(onClick = { navController.navigate(Patient( "Jane Smith-Baker", 33)) }) { Text("Pass 'Jane Smith-Baker' and 33 to the Person screen") } } } composable<Id> {...} composable<Patient> {...} } }

In wasmJsMain/kotlin/main.kt, add the lambda to the .bindToNavigation() call:

@OptIn(
    ExperimentalComposeUiApi::class,
    ExperimentalBrowserHistoryApi::class,
    ExperimentalSerializationApi::class
)
fun main() {
    val body = document.body ?: return
    ComposeViewport(body) {
        val navController = rememberNavController()
        App(navController)
        LaunchedEffect(Unit) {
            window.bindToNavigation(navController) { entry ->
                val route = entry.destination.route.orEmpty()
                when {
                    // Identifies the route using its serial descriptor
                    route.startsWith(StartScreen.serializer().descriptor.serialName) -> {
                        // Sets the corresponding URL fragment to "#start"
                        // instead of "#org.example.app.StartScreen"
                        //
                        // This string must always start with the `#` character to keep
                        // the processing at the front end
                        "#start"
                    }
                    route.startsWith(Id.serializer().descriptor.serialName) -> {
                        // Accesses the route arguments
                        val args = entry.toRoute<Id>()

                        // Sets the corresponding URL fragment to "#find_id_222"
                        // instead of "#org.example.app.ID%2F222"
                        "#find_id_${args.id}"
                    }
                    route.startsWith(Patient.serializer().descriptor.serialName) -> {
                        val args = entry.toRoute<Patient>()
                        // Sets the corresponding URL fragment to "#patient_Jane%20Smith-Baker_33"
                        // instead of "#org.company.app.Patient%2FJane%2520Smith-Baker%2F33"
                        "#patient_${args.name}_${args.age}"
                    }
                    // Doesn't set a URL fragment for all other routes
                    else -> ""
                }
            }
        }
    }
}

If your URLs have custom formatting, you should add the reverse processing to match manually entered URLs to destination routes. The code that does the matching needs to run before the window.bindToNavigation() call binds window.location to the navigation graph:

@OptIn(
    ExperimentalComposeUiApi::class,
    ExperimentalBrowserHistoryApi::class,
    ExperimentalSerializationApi::class
)
fun main() {
    val body = document.body ?: return
    ComposeViewport(body) {
        val navController = rememberNavController()
        App(navController)
        LaunchedEffect(Unit) {
            // Accesses the fragment substring of the current URL
            val initRoute = window.location.hash.substringAfter('#', "")
            when  {
                // Identifies the corresponding route and navigates to it
                initRoute.startsWith("start") -> {
                    navController.navigate(StartScreen)
                }
                initRoute.startsWith("find_id") -> {
                    // Parses the string to extract route parameters before navigating to it
                    val id = initRoute.substringAfter("find_id_").toLong()
                    navController.navigate(Id(id))
                }
                initRoute.startsWith("patient") -> {
                    val name = initRoute.substringAfter("patient_").substringBefore("_")
                    val id = initRoute.substringAfter("patient_").substringAfter("_").toLong()
                    navController.navigate(Patient(name, id))
                }
            }
            
            window.bindToNavigation(navController) { ... }
        }
    }
}

Third-party alternatives

If the Compose Multiplatform navigation components do not solve your problems, there are third-party alternatives that you can choose from:

Name	Description
Voyager	A pragmatic approach to navigation
Decompose	An advanced approach to navigation that covers the full lifecycle and any potential dependency injection
Appyx	Model-driven navigation with gesture control
PreCompose	A navigation and view model inspired by Jetpack Lifecycle, ViewModel, LiveData, and Navigation
Circuit	A Compose-driven architecture for Kotlin applications with navigation and advanced state management.

Last modified: 08 January 2025

Kotlin Multiplatform Development Help