Enables handling of screen results for Compose Navigation3, addressing the absence of native support for screen result handling. Utilizes SavedState architecture, ensuring reactivity and state persistence across screens.
ResultState provides the ability to handle screen results for Compose Navigation3.
Compose Navigation3 is a great library for navigating with stack data driven screen management, that encourages you to achieve your feature modules become more clearly separated and independently.
However, Navigation3 lacks a Screen Result handling API at this time. ResultState provides a Result API based on SavedState architecture for both Android Jetpack Compose and Compose Multiplatform.
The result values are stored into SavedState, and survive through Activity recreation or process restarting correctly. Also the saved results are tied to NavEntry's lifecycle, and cleared automatically when the receiver screen is popped out.
Add ResultState dependency to your project.
build.gradle.kts
plugins {
id("com.android.application")
// ...
}
dependencies {
// add ResultState dependency
implementation("io.github.irgaly.navigation3.resultstate:resultstate:1.2.0")
implementation("androidx.navigation3:navigation3-ui:...")
// ...
}
build.gradle.kts
plugins {
kotlin("multiplatform")
id("com.android.application")
id("org.jetbrains.compose")
id("org.jetbrains.kotlin.plugin.compose")
// ...
}
kotlin {
sourceSets {
commonMain {
dependencies {
// add ResultState dependency
implementation("io.github.irgaly.navigation3.resultstate:resultstate:1.2.0")
implementation("org.jetbrains.androidx.navigation3:navigation3-ui:...")
// ...
}
}
}
// ...
}
ResultState holds the all results as "String", that is for aiming to easily saved on SavedState architecture.
result key is just a "String".result value is just a "String".So you can produce a result as String with a String result key.
To use ResultState, follow this steps:
NavigationResultMetadata.resultConsumer() function.rememberNavigationResultNavEntryDecorator() to NavDisplay's entryDecorators.State<NavigationResult?> in the consumer screen by
LocalNavigationResultConsumer.Here is an example of an Android Compose project.
Compose Multiplatform project's sample is also available in sample/app/src/commonMain/kotlin/io/github/irgaly/navigation3/resultstate/sample/App.kt.
Next, receive the result as State<NavigationResult?> in Screen1.
Finally, produce the result from Screen2.
@Composable
fun Screen2(...) {
val resultProducer: NavigationResultProducer = LocalNavigationResultProducer.current
Column {
Text("Screen2")
Button(onClick = {
// 4.
// Produce the result for "Screen2Result" key.
// The result key and value are just a String.
resultProducer.setResult(
"Screen2Result",
"my result of screen2!",
)
}) {
Text("Set a result to \"Screen2Result\" key")
}
}
}
That's all!
You can receive the Screen2's result "my result of screen2!" from Screen1, when reentered to Screen1 or realtime because of the result is observed by Screen1 as a State.
ResultState supports to handle the typed result keys and the value as any Serializable type. Serialization support is provided by extension functions.
Here is an example.
There are some more code examples.
Receiver screen can receive multiple results from multiple producer screens.
Here is an example that assuming:
In this situation, if you'd like to wait for both Screen2Result and Screen3Result are produced, you can observe both states by single LaunchedEffect. This is an usual Compose way.
ResultState will store all results in a MutableState<Map<String, Map<String, String>>>,
that is defined in rememberNavigationResultNavEntryDecorator() or
rememberNavigationResultStateHolder() and it is held by NavigationResultStateHolder.
This map contains all values as String, so it can be saved by SavedState.
@Composable
fun <T : Any> rememberNavigationResultNavEntryDecorator(
backStack: List<T>,
entryProvider: (T) -> NavEntry<*>,
contentKeyToString: (Any) -> String = { it.toString() },
savedStateResults: MutableState<Map<String, Map<String, String>>> = rememberSaveable {
mutableStateOf(emptyMap())
},
): NavEntryDecorator<T> {
navigationResultStateHolder = rememberNavigationResultStateHolder(
backStack = backStack,
entryProvider = entryProvider,
contentKeyToString = contentKeyToString,
savedStateResults = savedStateResults,
)
remember(navigationResultStateHolder) {
NavigationResultNavEntryDecorator(navigationResultStateHolder)
}
}
The map has the structure below:
Map<String, Map<String, String>>
Map<String, String>
So all consumer screens can store the result map on SavedState.
ResultState provides the result to all screens that registered as a consumer by NavEntry's metadata, so any multiple screens and any position at NavBackStack can consume the result.
This means:
The map's contents are associated with NavEntry's lifecycle.
Here is a state's lifecycle example:
"screen1".The scenario is as follows:
sequenceDiagram
participant NavigationResultStateHolder
participant AppNavHost
participant Screen1
participant Screen2
participant Screen3
AppNavHost->>+Screen1: Show
activate Screen1
Screen1->>+Screen2: Navigate
activate Screen2
Screen2->>NavigationResultStateHolder: produce screen2's result
Screen2->>+Screen3: Navigate
activate Screen3
Screen3->>NavigationResultStateHolder: produce screen3's result
Screen3->>Screen2: Back
deactivate Screen3
Screen2->>Screen1: Back
deactivate Screen2
deactivate Screen1
The initial state of ResultState map is empty:
| Map Key | Map Value |
|---|---|
| (empty) | (empty) |
Screen2 produced a result "result from screen2" for "Screen2Result" key.
The current ResultState map is:
| Map Key | Map Value |
|---|---|
"screen1" | "Screen2Result" to "result from screen2" |
Screen3 produced a result "result from screen3" for "Screen3Result" key.
The current ResultState map is:
| Map Key | Map Value |
|---|
Navigated back to Screen2, and Screen3 was popped out from the NavBackStack.
Screen3 holds no result in the ResultState map, so the map is not changed.
The current ResultState map is:
| Map Key | Map Value |
|---|
Then, Screen2 has consumed the "Screen3Result" result, and called
consumer.clearResult("Screen3Result").
So the ResultState map is:
| Map Key | Map Value |
|---|---|
"screen1" | "Screen2Result" to "result from screen2""Screen3Result" to |
Navigated back to Screen1, and Screen2 was popped out from the NavBackStack.
Screen2 holds no result in the ResultState map, so the map is not changed.
The current ResultState map is:
| Map Key | Map Value |
|---|---|
"screen1" | "Screen2Result" to "result from screen2""Screen3Result" to |
Then, Screen1 has consumed the "Screen2Result" result and "Screen3Result" result, then called
consumer.clearResult("Screen3Result"), consumer.clearResult("Screen3Result").
So the ResultState map is:
| Map Key | Map Value |
|---|---|
| (empty) | (empty) |
When it is navigated to Screen1 from Screen3 by skipping Screen2 showing, Screen2 can not consume
the
"Screen3Result" result.
The ResultState map is associated with NavEntry's lifecycle, so the results that the Screen2 holds are cleared automatically.
sequenceDiagram
participant Screen1
participant Screen2
participant Screen3
activate Screen1
Screen1->>+Screen2: Navigate
activate Screen2
Screen2->>+Screen3: Navigate
activate Screen3
Screen3->>Screen1: Back
deactivate Screen3
deactivate Screen2
deactivate Screen1
The Screen3 has showed and produced a result "result from screen3" to "Screen3Result" key.
The current ResultState map is:
| Map Key | Map Value |
|---|
Then, it navigated back to Screen1 from Screen3 directly, while the Screen2 was also popped out.
Screen2 did not consume the "Screen3Result" result, but the results for "screen2" are cleared
automatically.
Then current ResultState map is:
| Map Key | Map Value |
|---|---|
"screen1" | "Screen2Result" to "result from screen2""Screen3Result" to |
ResultState provides the results as observable State, so the produced results are consumed in realtime while the consumer screen is showing.
For example, Screen1 and Screen2 are both showing in a multi-pane SceneStrategy, and Screen2
produces a result, then Screen1 can consume the result in realtime by
LaunchedEffect(resultState) { ... }.
LocalNavigationResultProducer.// Android Compose project sample
interface Screen : NavKey
data object Screen1 : Screen
data object Screen2 : Screen
fun NavigationContent() {
val navBackStack = rememberNavBackStack(Screen1) as NavBackStack<Screen>
val entryProvider = entryProvider<Screen> {
entry<Screen1>(
// 1.
// Declare that the Screen1 want to receive the Screen2's result, so register "Screen2Result" key to metadata.
// The result key is just unique string tied to the Screen2's result.
metadata = metadata {
put(
NavigationResultMetadata.ResultConsumerKey,
NavigationResultMetadata.resultConsumer(
"Screen2Result",
),
)
},
) {
Screen1(...)
}
entry<Screen2> {
Screen2(...)
}
}
NavDisplay(
backStack = navBackStack,
onBack = { ... },
entryDecorators = listOf(
// 2.
// Set an NavigationResultNavEntryDecorator to NavDisplay.
// This decorator provides LocalNavigationResultProducer and LocalNavigationResultConsumer to NavEntries.
// The entryProvider must be the same one as NavDisplay's entryProvider.
// rememberNavigationResultNavEntryDecorator() will also create NavigationResultStateHolder that holds ResultState on SavedState.
rememberNavigationResultNavEntryDecorator(
backStack = navBackStack,
entryProvider = entryProvider,
),
rememberSaveableStateHolderNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator(),
),
entryProvider = entryProvider,
)
}
fun Screen1(...) {
var resultString: String by rememberSaveable { mutableStateOf("{empty}") }
// 3.
// Receive the result as ResultState.
val resultConsumer: NavigationResultConsumer = LocalNavigationResultConsumer.current
val screen2Result: NavigationResult? by remember(resultConsumer) {
// The result key is the same one as registered in Screen1's metadata.
resultConsumer.getResultState("Screen2Result")
}
LaunchedEffect(screen2Result) {
val result: NavigationResult? = screen2Result
if (result != null) {
// NavigationResult.result is just a String.
resultString = result.result
// Clear the result after received to avoid receiving it in next composition.
// Here, result.resultKey is "Screen2Result".
resultConsumer.clearResult(result.resultKey)
}
}
Column {
Text("Screen1")
Text("Received result is: $resultString")
}
}
interface Screen : NavKey
data object Screen1 : Screen
data object Screen2 : Screen
// Declare a serializable result data class.
data class Screen2Result(val result: String)
// Define Screen2's result key as SerializableNavigationResultKey's instance,
// The resultKey is "Screen2Result", and the result type is Screen2Result.
val Screen2ResultKey = SerializableNavigationResultKey<Screen2Result>(
serializer = Screen2Result.serializer(),
resultKey = "Screen2Result",
)
fun NavigationContent() {
val navBackStack = rememberNavBackStack(Screen1) as NavBackStack<Screen>
val entryProvider = entryProvider<Screen> {
entry<Screen1>(
metadata = metadata {
put(
NavigationResultMetadata.ResultConsumerKey,
NavigationResultMetadata.resultConsumer(
// Register Screen2ResultKey as typed key.
Screen2ResultKey,
),
)
},
) {
Screen1(...)
}
entry<Screen2> {
Screen2(...)
}
}
NavDisplay(
backStack = navBackStack,
onBack = { ... },
entryDecorators = listOf(
rememberNavigationResultNavEntryDecorator(
backStack = navBackStack,
entryProvider = entryProvider,
),
rememberSaveableStateHolderNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator(),
),
entryProvider = entryProvider,
)
}
fun Screen1(...) {
val resultConsumer: NavigationResultConsumer = LocalNavigationResultConsumer.current
var resultString: String by rememberSaveable { mutableStateOf("{empty}") }
val screen2Result: SerializedNavigationResult<Screen2Result>? by remember(resultConsumer) {
resultConsumer.getResultState(Screen2ResultKey)
// Pass the json instance and typed key when custom Json instance is needed.
//resultConsumer.getResultState(Screen2ResultKey, json)
}
LaunchedEffect(screen2Result) {
val result: SerializedNavigationResult<Screen2Result>? = screen2Result
if (result != null) {
// The received result is just a String, but getResult() will decode it to a Screen2Result instance.
val screen2Result: Screen2Result = result.getResult()
resultString = screen2Result.result
resultConsumer.clearResult(result.resultKey)
}
}
Column {
Text("Screen1")
Text("Received result is: $resultString")
}
}
fun Screen2(...) {
val resultProducer: NavigationResultProducer = LocalNavigationResultProducer.current
Column {
Text("Screen2")
Button(onClick = {
resultProducer.setResult(
Screen2ResultKey,
Screen2Result("my result of screen2!"),
)
// Pass the json instance and typed key when custom Json instance is needed.
//resultProducer.setResult(
// Screen2ResultKey,
// Screen2Result("my result of screen2!"),
// json,
//)
}) {
Text("Set a result to Screen2ResultKey")
}
}
}
interface Screen : NavKey
data object Screen1 : Screen
data object Screen2 : Screen
data object Screen3 : Screen
// Declare serializable result data classes.
data class Screen2Result(val result: String)
data class Screen3Result(val result: String)
// Define result keys as SerializableNavigationResultKey's instance,
val Screen2ResultKey = SerializableNavigationResultKey<Screen2Result>(
serializer = Screen2Result.serializer(),
resultKey = "Screen2Result",
)
val Screen3ResultKey = SerializableNavigationResultKey<Screen3Result>(
serializer = Screen3Result.serializer(),
resultKey = "Screen3Result",
)
fun NavigationContent() {
val navBackStack = rememberNavBackStack(Screen1) as NavBackStack<Screen>
val entryProvider = entryProvider<Screen> {
entry<Screen1>(
metadata = metadata {
put(
NavigationResultMetadata.ResultConsumerKey,
NavigationResultMetadata.resultConsumer(
// Screen1 wants to receive a Screen2Result and a Screen3Result.
Screen2ResultKey,
Screen3ResultKey,
),
)
},
) {
Screen1(...)
}
entry<Screen2> {
Screen2(...)
}
entry<Screen3> {
Screen3(...)
}
}
NavDisplay(
backStack = navBackStack,
onBack = { ... },
entryDecorators = listOf(
rememberNavigationResultNavEntryDecorator(
backStack = navBackStack,
entryProvider = entryProvider,
),
rememberSaveableStateHolderNavEntryDecorator(),
rememberViewModelStoreNavEntryDecorator(),
),
entryProvider = entryProvider,
)
}
fun Screen1(...) {
val resultConsumer: NavigationResultConsumer = LocalNavigationResultConsumer.current
var result2String: String by rememberSaveable { mutableStateOf("{empty}") }
val screen2Result: SerializedNavigationResult<Screen2Result>? by remember(resultConsumer) {
// Receives Screen2Result as State.
resultConsumer.getResultState(Screen2ResultKey)
}
LaunchedEffect(screen2Result) {
val result: SerializedNavigationResult<Screen2Result>? = screen2Result
if (result != null) {
// Receives deserialized Screen2Result instance, and clear it from ResultState.
val screen2Result: Screen2Result = result.getResult()
screen2String = screen2Result.result
resultConsumer.clearResult(result.resultKey)
}
}
var result3String: String by rememberSaveable { mutableStateOf("{empty}") }
val screen3Result: SerializedNavigationResult<Screen3Result>? by remember(resultConsumer) {
// Receives Screen3Result as State.
resultConsumer.getResultState(Screen3ResultKey)
}
LaunchedEffect(screen3Result) {
val result: SerializedNavigationResult<Screen3Result>? = screen3Result
if (result != null) {
// Receives deserialized Screen3Result instance, and clear it from ResultState.
val screen3Result: Screen3Result = result.getResult()
screen3String = screen3Result.result
resultConsumer.clearResult(result.resultKey)
}
}
Column {
Text("Screen1")
Text("Received Screen2's result is: $result2String")
Text("Received Screen3's result is: $result3String")
}
}
fun Screen2(...) {
val resultProducer: NavigationResultProducer = LocalNavigationResultProducer.current
Column {
Text("Screen2")
Button(onClick = {
resultProducer.setResult(
Screen2ResultKey,
Screen2Result("my result of screen2!"),
)
}) {
Text("Set a result to Screen2ResultKey")
}
}
}
fun Screen3(...) {
val resultProducer: NavigationResultProducer = LocalNavigationResultProducer.current
Column {
Text("Screen3")
Button(onClick = {
resultProducer.setResult(
Screen3ResultKey,
Screen3Result("my result of screen3!"),
)
}) {
Text("Set a result to Screen3ResultKey")
}
}
}
// The example of waiting for both results are produced.
fun Screen1(...) {
val resultConsumer: NavigationResultConsumer = LocalNavigationResultConsumer.current
var result2String: String by rememberSaveable { mutableStateOf("{empty}") }
var result3String: String by rememberSaveable { mutableStateOf("{empty}") }
val screen2Result: SerializedNavigationResult<Screen2Result>? by remember(resultConsumer) {
// Receives Screen2Result as State.
resultConsumer.getResultState(Screen2ResultKey)
}
val screen3Result: SerializedNavigationResult<Screen3Result>? by remember(resultConsumer) {
// Receives Screen3Result as State.
resultConsumer.getResultState(Screen3ResultKey)
}
LaunchedEffect(screen2Result, screen3Result) {
val result2: SerializedNavigationResult<Screen2Result>? = screen2Result
val result3: SerializedNavigationResult<Screen3Result>? = screen3Result
if (result2 != null && result3 != null) {
// Receives both results, and clear them from ResultState.
val screen2Result: Screen2Result = result2.getResult()
val screen3Result: Screen3Result = result3.getResult()
result2String = screen2Result.result
result3String = screen3Result.result
resultConsumer.clearResult(result2.resultKey)
resultConsumer.clearResult(result3.resultKey)
}
}
Column {
Text("Screen1")
Text("Received Screen2's result is: $result2String")
Text("Received Screen3's result is: $result3String")
}
}
"screen2"."screen3"."Screen2Result" key and "Screen3Result" key."Screen3Result" key."screen1" | "Screen2Result" to "result from screen2""Screen3Result" to "result from screen3" |
"screen2" | "Screen3Result" to "result from screen3" |
"screen1" | "Screen2Result" to "result from screen2""Screen3Result" to "result from screen3" |
"screen2" | "Screen3Result" to "result from screen3" |
"result from screen3""result from screen3""screen1" | "Screen2Result" to "result from screen2""Screen3Result" to "result from screen3" |
"screen2" | "Screen3Result" to "result from screen3" |
"result from screen3"Surfaced from shared tags and platforms — no rankings paid for.