Kotlin Multiplatform Help

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.9.0-beta04") } // ... } }

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:

  1. List routes that should be included in the navigation graph. Each route must be a unique string that defines a path.

  2. Create a NavHostController instance as your main composable property to manage navigation.

  3. 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.

Support for browser navigation in web apps

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, you can use the window.bindToNavigation() method in your Kotlin/Wasm code. You can use the same method in Kotlin/JS, but wrap it in the onWasmReady {} block to ensure that the Wasm application is initialized and Skia is ready to render graphics. Here is an example of how to set this up:

//commonMain source set @Composable fun App( onNavHostReady: suspend (NavController) -> Unit = {} ) { val navController = rememberNavController() NavHost(...) { //... } LaunchedEffect(navController) { onNavHostReady(navController) } } //wasmJsMain source set @OptIn(ExperimentalComposeUiApi::class) @ExperimentalBrowserHistoryApi fun main() { val body = document.body ?: return ComposeViewport(body) { App( onNavHostReady = { window.bindToNavigation(it) } ) } } //jsMain source set @OptIn(ExperimentalComposeUiApi::class) @ExperimentalBrowserHistoryApi fun main() { onWasmReady { val body = document.body ?: return@onWasmReady ComposeViewport(body) { App( onNavHostReady = { window.bindToNavigation(it) } ) } } }

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:

  1. Pass the optional getBackStackEntryRoute lambda to the window.bindToNavigation() function to specify how routes should be converted into URL fragments when necessary.

  2. 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( onNavHostReady: suspend (NavController) -> Unit = {} ) = AppTheme { val navController = rememberNavController() 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> {...} } LaunchedEffect(navController) { onNavHostReady(navController) } }

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) { App( onNavHostReady = { navController -> 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) { App( onNavHostReady = { navController -> // 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) { ... } } ) } }
@OptIn( ExperimentalComposeUiApi::class, ExperimentalBrowserHistoryApi::class, ExperimentalSerializationApi::class ) fun main() { onWasmReady { val body = document.body ?: return@onWasmReady ComposeViewport(body) { App( onNavHostReady = { navController -> // 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) { ... } } ) } } }
Last modified: 22 July 2025