Facilitates the retention and cleanup of ViewModels or objects within composable functions, ensuring lifecycle management across recompositions, configuration changes, and backstack navigation. Supports dependency injection and provides fine-grained state management.
Article about this library: Every Composable deserves a ViewModel
The right scope for objects and View Models in Android Compose.
Resaca provides a simple way to keep a Jetpack ViewModel (or any other object) in memory during the lifecycle of a @Composable function and automatically
clean it up when not needed anymore. This means, it retains your object or ViewModel across recompositions, during configuration changes, and also when the
container Fragment or Compose Navigation destination goes into the backstack.
With Resaca you can create fine grained ViewModels for fine grained Composables and finally have reusable components across screens.
Compose allows the creation of fine-grained UI components that can be easily reused like Lego blocks 🧱. Well architected Android apps isolate functionality in small business logic components (like use cases, interactors, repositories, etc.) that are also reusable like Lego blocks 🧱.
Screens are built using Compose components together with business logic components, and the standard tool to connect these two types of components is a Jetpack ViewModel. Unfortunately, ViewModels can only be scoped to a whole screen (or larger scope), but not to smaller Compose components on the screen.
In practice, this means that we are gluing UI Lego blocks with business logic Lego blocks using a big glue class for the whole screen, the ViewModel 🗜.
Until now...
Just include the library (less than 5Kb):
// In module's build.gradle.kts
dependencies {
// The latest version of the lib is available in the badget at the top from Maven Central, replace X.X.X with that version
implementation("io.github.sebaslogen:resaca:X.X.X")
}
dependencies {
// The latest version of the lib is available in the badget at the top from Maven Central, replace X.X.X with that version
implementation 'io.github.sebaslogen:resaca:X.X.X'
}
Inside your @Composable function create and retrieve an object using rememberScoped to remember any type of object (except ViewModels). For ViewModels use
viewModelScoped. That's all 🪄✨
Examples:
@Composable
fun DemoScopedObject() {
val myRepository: MyRepository = rememberScoped { MyRepository() }
DemoComposable(inputObject = myRepository)
}
@Composable
fun DemoScopedViewModel() {
val myScopedVM: MyViewModel = viewModelScoped()
DemoComposable(inputObject = myScopedVM)
}
@Composable
fun DemoScopedViewModelWithDependency() {
val myScopedVM: MyViewModelWithDependencies = viewModelScoped { MyViewModelWithDependencies(myDependency) }
DemoComposable(inputObject = myScopedVM)
}
@Composable
fun DemoViewModelWithKey() {
val scopedVMWithFirstKey: MyViewModel = viewModelScoped("myFirstKey") { MyViewModel("myFirstKey") }
val scopedVMWithSecondKey: MyViewModel = viewModelScoped("mySecondKey") { MyViewModel() }
DemoComposable(inputObject = scopedVMWithFirstKey)
DemoComposable(inputObject = scopedVMWithSecondKey)
}
@Composable
fun DemoKoinInjectedViewModelWithDependency() {
val myInjectedScopedVM: MyViewModelWithDependencies = viewModelScoped() { getKoin().get { parametersOf(myConstructorDependency) } }
DemoComposable(inputObject = myInjectedScopedVM)
}
@Composable
fun DemoMetroInjectedViewModelScoped() {
val myInjectedScopedVM: MyViewModel = metroViewModelScoped(factory = myMetroViewModelFactory)
DemoComposable(inputObject = myInjectedScopedVM)
}
@Composable
fun DemoScopedViewModelWithClearDelay() {
// The ViewModel will be kept in memory for 5 seconds after the Composable is disposed,
// giving it a chance to be reused if the Composable returns to composition (e.g. quick navigation back and forth)
val myScopedVM: MyViewModel = viewModelScoped(clearDelay = 5.seconds)
DemoComposable(inputObject = myScopedVM)
}
@Composable
fun DemoScopedObjectWithClearDelay() {
val myRepository: MyRepository = rememberScoped(clearDelay = 5.seconds) { MyRepository() }
DemoComposable(inputObject = myRepository)
}
@Composable
fun DemoManyViewModelsScopedOutsideTheLazyColumn(listItems: List<Int> = (1..1000).toList()) {
val keys = rememberKeysInScope(inputListOfKeys = listItems)
LazyColumn() {
items(items = listItems, key = { it }) { item ->
myScopedVM: MyViewModel = viewModelScoped(key = item, keyInScopeResolver = keys)
DemoComposable(inputObject = myScopedVM)
}
}
}
Once you use the rememberScoped or viewModelScoped functions, the same object will be restored as long as the Composable is part of the composition, even if
it temporarily leaves composition on configuration change (e.g. screen rotation, change to dark mode, etc.) or while being in the backstack.
For ViewModels, in addition to being forgotten when they're really not needed anymore, their coroutineScope will also be automatically canceled because
ViewModel's onCleared method will be automatically called.
💡 Optional key: a key can be provided to the call,
rememberScoped(key) { ... }orviewModelScoped(key) { ... }. This makes possible to forget an old object when there is new input data during a recomposition (e.g. a new input id for your ViewModel).
💡 Optional clearDelay: a
clearDelaycan be provided to delay the disposal of the scoped object after the Composable is removed from composition. This is useful when a Composable might briefly leave composition and return (e.g. quick navigation back and forth), and you want to avoid recreating expensive objects. Usage:rememberScoped(clearDelay = 5.seconds) { ... }orviewModelScoped(clearDelay = 5.seconds). If the Composable returns to composition before the delay expires, the disposal is cancelled and the same object is reused.
⚠️ Note that ViewModels remembered with
viewModelScopedshould not be created using any of the ComposeviewModel()orViewModelProvidersfactories, otherwise they will be retained in the scope of the screen regardless of . Also, if a ViewModel is remembered with , instead of , then its clean-up method won't be called, so it's always better to use for ViewModels.
Here are some sample use cases reported by the users of this library:
Demo app documentation can be found here.
| Before | After backstack navigation & configuration change |
|---|---|
 |  |
Since version 4.0, Resaca supports Compose Multiplatform for Android, iOS, Desktop-JVM and Web targets. To see an example of usage and configuration check the in the module.
This library does not influence how your app provides or creates objects so it's dependency injection strategy and framework agnostic.
Nevertheless, this library supports three of the main dependency injection frameworks:
HILT (Dagger) support is available in a small extension of this library: resaca-hilt.
Documentation and installation instructions are available here.
This is handy for the typical case where you have a lazy list of items and you want to have a separate ViewModel for each item in the list, using the viewModelScoped function.
When a Composable is used more than once in the same screen with the same input, then the ViewModel (or business logic object) should be provided only once
with viewModelScoped at a higher level in the composition tree using Compose's State Hoisting.
Surfaced from shared tags and platforms — no rankings paid for.
viewModelScopedrememberScopedviewModelScopedviewModelScopedFavoriteViewModel can be very small, focused
and only require an id to work without affecting the rest of the screen's UI and state.HolidayDestinationViewModel.samplecmpResaca is a Kotlin Multiplatform library and can be used in any Kotlin Multiplatform project that targets Android, iOS, Desktop-JVM and Web. Nevertheless, Resaca does not make sense in a SwiftUI project because it's a Compose only library, instead, if you want to scope ViewModels to SwiftUI views, you can look at the solutions provided in the first comments of this ticket https://github.com/sebaslogen/resaca/issues/91.
Koin is out of the box supported by simply changing the way you request a dependency.
Instead of using the getViewModel or koinViewModel functions from Koin, you have to use the standard way of getting a dependency from Koin getKoin().get().
Usage example: val viewModel: MyViewModel = viewModelScoped(myId) { getKoin().get { parametersOf(myId) } }
Note: if you plan to use a ViewModel with a SavedStateHandle, then you need to use the
koinViewModelScopedfunction from the small extension library resaca-koin.
Metro is a Kotlin-first dependency injection framework that uses a compiler plugin for compile-time dependency graph validation and code generation. Metro is supported through the small extension library resaca-metro.
Usage example:
val viewModel: MyViewModel = metroViewModelScoped(factory = myMetroViewModelFactory)
Where myMetroViewModelFactory is a ViewModelProvider.Factory backed by your Metro @DependencyGraph.
Metro's assisted injection is also supported:
val viewModel: MyViewModel = metroViewModelScoped(
key = myId,
factory = createAssistedFactory(metroGraph, myId)
)
When using the Lazy* family of Composables it is recommended that -just above the call to the Lazy* Composable- you use rememberKeysInScope with a list of
keys corresponding to the items used in the Lazy* Composable to obtain a KeyInScopeResolver (it's already highly recommended in Compose that items in a Lazy* list have unique keys).
Then, in the Lazy* Composable, once you are creating an item and you need an object or ViewModel for that item,
all you have to do is include in the call to rememberScoped/viewModelScoped the key for the current item and the KeyInScopeResolver you previously got from rememberKeysInScope.
With this setup, when an item of the Lazy* list becomes visible for the first time, its associated rememberScoped/viewModelScoped object will be created and even if the item is scrolled away, the scoped object will still be alive. Only once the associated key is not present anymore in the list provided to rememberKeysInScope and the item is either not part of the Lazy* list anymore or scrolled away, then the associated object will be cleared and destroyed.
🏷️ Example of a separate ViewModel for each item in a LazyColumn and scope them to the Composable that contains the LazyColumn
@Composable
fun DemoManyViewModelsScopedOutsideTheLazyColumn(listItems: List<Int> = (1..1000).toList()) {
val keys = rememberKeysInScope(inputListOfKeys = listItems)
LazyColumn() {
items(items = listItems, key = { it }) { item ->
val myScopedVM: MyViewModel = viewModelScoped(key = item, keyInScopeResolver = keys)
DemoComposable(inputObject = myScopedVM)
}
}
}
You can use clearDelay alongside keyInScopeResolver in the same Lazy* list. This is useful when some items need a grace period before being cleared (e.g. the first item uses clearDelay for a smoother experience) while others should stay in memory as long as they are in the list (via keyInScopeResolver).
💡 Note:
clearDelayandkeyInScopeResolverare independent mechanisms. An item usingclearDelaywithoutkeyInScopeResolverwill be cleared after the delay, regardless of whether it is still in the list. An item usingkeyInScopeResolverwithoutclearDelaywill be kept alive as long as its key is present in the list.
🏷️ Example of a LazyColumn where the first item uses clearDelay and the rest use keyInScopeResolver
@Composable
fun DemoMixedScopingInLazyColumn(listItems: List<Int> = (1..1000).toList()) {
val keys = rememberKeysInScope(inputListOfKeys = listItems)
LazyColumn() {
items(items = listItems, key = { it }) { item ->
val myScopedVM: MyViewModel = if (item == 1) {
// This item's ViewModel will be cleared 5 seconds after scrolling away
viewModelScoped(key = item, clearDelay = 5.seconds)
} else {
// These items' ViewModels stay alive as long as the item is in the list
viewModelScoped(key = item, keyInScopeResolver = keys)
}
DemoComposable(inputObject = myScopedVM)
}
}
}
Remember will keep our object alive as long as the Composable is not disposed of. Unfortunately, there are a few cases where our Composable will be disposed of and then added again, breaking the lifecycle parity with the remember function. 😢
Pros
Cons
RememberSaveable will follow the lifecycle of the Composable, even in the few cases where the Composable is temporarily disposed of. But the object we want to remember needs to implement Parcelable or the Saver interface in an additional class. 😢 Implementing these interfaces might not trivial.
Pros
Cons
RememberScoped function keeps
objects in memory during the lifecycle of the Composable, even in a few cases where the Composable is disposed of, and then added again. Therefore, it will
retain objects longer than the remember function but shorter than rememberSaveable because there is no serialization involved.
Pros
Cons
RememberScoped function keeps objects in memory during the lifecycle of the Composable, even in a few cases where the Composable is disposed of, and then added again.
This project uses internally a ViewModel as a container to store all scoped ViewModels and scoped objects.
When a Composable is disposed of, we don't know for sure if it will return again later. So at the moment of disposal, we mark in our container the associated object to be disposed of after the next frame when the Activity is resumed. During the span of time of this next frame, a few things can happen:
rememberScoped/viewModelScoped function restores the associated object while also
cancelling any pending disposal in the next frame when the Activity is resumed. 🎉Note:
rememberSaveable
, which survives recomposition, recreation and even process death.
This diagram shows the lifecycle of three Composables (A, B, and C) with their respective objects scoped with the rememberScoped function. All these
Composables are part of a Composable destination which is part of a Fragment which is part of an Activity which is part of the App. The horizontal arrows
represent different lifecycle events, events like Composable being disposed of, Composable screen going into the backstack, Fragment going into the backstack
and returning from backstack, or Activity recreated after a configuration change.
The existing alternatives to replicate the lifecycle of the objects in the diagram without using rememberScoped are:
viewModel() or ViewModelProviders factories.remember() function.remember functions.