A Compose-multiplatform navigation library that leverage Decompose to create an API inspired by Conductor
A detailed breakdown available in this Medium article
- ๐ A
Router
that manages a FILO stack for your screen configurations - ๐ฆ
rememberOnRoute()
lets you retain your view model across configuration changes and gets cleared when the user leaves the screen - โ ๏ธ A
SavedStateHandle
to restore state gracefully after the process death. (for Android) - ๐ Multiplatform! Supports Android, WearOS, Desktop, iOS and Web
Decompose-Router is published on Maven Central
repositories {
mavenCentral()
// or for snapshot builds
maven("https://s01.oss.sonatype.org/content/repositories/snapshots/")
}
Include the dependency in commonMain
. Latest version
Note Check for compatible versions of Compose Multiplatform, Decompose and Essenty in the Version Catalog
1. With version catalog
libs.version.toml
[versions]
# Check in gradle/libs.versions.toml
[libraries]
# For Compose Multiplatform
decompose-router = { module = "io.github.xxfast:decompose-router", version.ref = "decompose-router" }
# For Compose Wear
decompose-router-wear = { module = "io.github.xxfast:decompose-router-wear", version.ref = "decompose-router" }
# You will need to also bring in decompose and essenty
decompose = { module = "com.arkivanov.decompose:decompose", version.ref = "decompose" }
decompose-compose-multiplatform = { module = "com.arkivanov.decompose:extensions-compose-jetbrains", version.ref = "decompose" }
essenty-parcelable = { module = "com.arkivanov.essenty:parcelable", version.ref = "essenty" }
build.gradle.kts
sourceSets {
// For Compose Multiplatform
val commonMain by getting {
dependencies {
implementation(libs.decompose.router)
// You will probably need to also bring in decompose and essenty
implementation(libs.decompose)
implementation(libs.decompose.compose.multiplatform)
implementation(libs.essenty.parcelable)
}
}
// For Compose Wear
val androidMain by getting {
dependencies {
implementation(libs.decompose.router.wear)
}
}
}
2. Without version catalog
build.gradle.kts
sourceSets {
// For Compose Multiplatform
val commonMain by getting {
dependencies {
implementation("io.github.xxfast:decompose-router:${versions.decompose-router}")
// You will need to also bring in decompose and essenty
implementation("com.arkivanov.decompose:decompose:${versions.decompose}")
implementation("com.arkivanov.decompose:extensions-compose-jetbrains:${versions.decompose}")
implementation("com.arkivanov.essenty:parcelable:${versions.essenty}")
}
}
// For Compose Wear
val androidMain by getting {
dependencies {
implementation("io.github.xxfast:decompose-router-wear:${versions.decompose-router}")
}
}
}
// Declare your screen configurations for type-safety
@Parcelize
sealed class Screen: Parcelable {
object List : Screen()
data class Details(val detail: String) : Screen()
}
@Composable
fun ListDetailScreen() {
// Create a router with a stack of screen configurations ๐
val router: Router<Screen> = rememberRouter { listOf(List) }
// Hoist your screens for each configuration ๐๏ธ
RoutedContent(router = router) { screen ->
when (screen) {
List -> ListScreen(
// Navigate by pushing new configurations on the router ๐งญ
onSelectItem = { detail -> router.push(detail) }
)
is Details -> DetailsScreen(screen.detail)
}
}
}
@Composable
fun DetailsScreen(detail: String) {
// ๐ฆ Scope an instance (a view model, a state-holder or whatever) to a route with [rememberOnRoute]
// This makes your instances survive configuration changes (on android) ๐
// And holds-on the instance as long as it is in the backstack ๐
// Pass in key if you want to reissue a new instance when key changes ๐ (optional)
val instance: DetailInstance = rememberOnRoute(key = detail) { savedState -> DetailInstance(savedState, detail) }
val state: DetailState by instance.states.collectAsState()
Text(text = state.detail)
}
// If you want your state to survive process death โ ๏ธ derive your initial state from [SavedStateHandle]
class DetailInstance(savedState: SavedStateHandle, detail: String) : InstanceKeeper.Instance {
private val initialState: DetailState = savedState.get() ?: DetailState(detail)
private val stateFlow = MutableStateFlow(initialState)
val states: StateFlow<DetailState> = stateFlow
}
Android / WearOS
build.gradle.kts
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val rootRouterContext: RouterContext = defaultRouterContext()
setContent {
CompositionLocalProvider(LocalRouterContext provides rootRouterContext) {
MaterialTheme {
ListDetailScreen()
}
}
}
}
}
Desktop
build.gradle.kts
fun main() {
val lifecycle = LifecycleRegistry()
val rootRouterContext = RouterContext(lifecycle = lifecycle)
application {
Window {
CompositionLocalProvider(LocalRouterContext provides rootRouterContext) {
MaterialTheme {
ListDetailScreen()
}
}
}
}
}
iOS
Make sure to create your root router context outside of ComposeUIViewController
's composable lambda and pass it in to LocalRouterContext
build.gradle.kts
fun MainUIController(rootRouterContext: RouterContext): UIViewController = ComposeUIViewController {
CompositionLocalProvider(LocalRouterContext provides rootRouterContext) {
MaterialTheme {
ListDetailScreen()
}
}
}
[!IMPORTANT] You will need to tie root
RouterContext
's lifecycle to anAppDelegate
. See example kotlin app delegate here, or swift delegate here. Read more on the docs here
Web
See example here, or read more on docs here
build.gradle.kts
fun main() {
onWasmReady {
val rootRouterContext: RouterContext = defaultRouterContext()
BrowserViewportWindow(..) {
CompositionLocalProvider(LocalRouterContext provides rootRouterContext) {
MaterialTheme {
ListDetailScreen()
}
}
}
}
}
Copyright 2023 Isuru Rajapakse
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.