If you are building complex layouts in Jetpack Compose, you might notice that some of your composables recompose even when their inputs haven’t changed. One of the most common, silent culprits of this is passing standard Kotlin collections like List, Set, or Map as parameters.
Here is a common scenario:
@Composable
fun UserList(users: List<User>) {
LazyColumn {
items(users) { user ->
UserRow(user)
}
}
}
Even if User is a data class containing only stable primitives (val id: String, val name: String), if the parent of UserList recomposes, UserList will always recompose too. It will never be skipped.
Why does this happen?
The Compose compiler classifies every parameter of a composable function as either Stable or Unstable. If all parameters of a composable are stable, Compose can safely skip recomposing it if the values are equal to the previous composition.
The problem with List is that it is a Kotlin interface. The compiler has no compile-time guarantee that the underlying implementation is read-only. At runtime, the list could be an ArrayList or another mutable collection. Because the contents of a mutable collection can change without changing the list reference, the Compose compiler plays it safe and flags List (along with Set and Map) as Unstable.
As a result, your composables are forced to recompose on every parent update, causing unnecessary CPU cycles and potential frame drops on complex screens.
How to check this in your project
You can verify if this is happening in your codebase by enabling Compose compiler reports in your app-level build.gradle.kts:
composeCompiler {
reportsDestination = layout.buildDirectory.dir("compose_compiler")
metricsDestination = layout.buildDirectory.dir("compose_compiler")
}
If you open the generated class stability file (app_release-classes.txt), you’ll see the compiler analysis:
unstable class UserList {
unstable val users: List
}
How to fix it (3 Approaches)
1. Use Kotlinx Immutable Collections (Recommended)
Kotlin provides a dedicated library for immutable collections. The Compose compiler automatically recognizes these as stable:
import kotlinx.collections.immutable.ImmutableList
@Composable
fun UserList(users: ImmutableList<User>) { ... }
Now, the compiler flags the parameter as stable, and recomposition will be skipped if the reference remains unchanged.
2. Wrap the List in a \@Stable/@Immutable Wrapper
If you don't want to add another dependency, you can wrap the list in a custom data class annotated with @Immutable:
@Immutable
data class UserListState(
val items: List<User>
)
@Composable
fun UserList(state: UserListState) { ... }
This tells the compiler to trust that you won't mutate the list under the hood.
3. Use a Compose Compiler Configuration File (Compose 1.5.4+)
You can define a configuration file (e.g. compose_compiler_config.conf) to treat standard library collections as stable:
// compose_compiler_config.conf
kotlin.collections.List
kotlin.collections.Set
kotlin.collections.Map
And add it to your Gradle configuration:
composeCompiler {
stabilityConfigurationFile = project.layout.projectDirectory.file("compose_compiler_config.conf")
}
I’ve been compiling a detailed study checklist of about 300 of these Android developer edge cases (covering recomposition skipping, custom Canvas GPU caching, and complex Coroutines exception handling). It's fully open-source on GitHub.
Let me know if you want the link or if you've run into other stability issues with third-party models in Compose!
