A List<String> parameter can quietly turn off skipping for an entire subtree. Here is how the compiler decides, how to prove it, and when to stop caring.
You open Layout Inspector, scroll a podcast queue, and watch the recomposition counter on every row climb in lockstep with a progress ticker that has nothing to do with the rows. The data is identical. The UI is identical. Compose is still re-running your code.
Nine times out of ten the cause is the same: the compiler could not prove that one of your parameters was unchanged, so it stopped trying to skip. This post walks through that decision, the failure modes that trigger it in real codebases, and the fixes, in the order you will actually need them.
1. Recomposition and skipping in one diagram
When state read by a composable changes, Compose re-executes that composable. Every child call inside it then gets a chance to be skipped: the compiler-generated code compares each argument with the value from the previous call and, if all of them match, reuses the earlier result instead of running the child’s body.
Our running example is a queue screen in a podcast app:
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.runtime.Composable
import androidx.compose.runtime.Immutable
@Immutable
@JvmInline
value class EpisodeId(val value: Long)
data class Episode(
val id: EpisodeId,
val title: String,
val tags: List<String>,
)
data class QueueUiState(
val episodes: List<Episode>,
val playingId: EpisodeId?,
val positionMs: Long, // updated every 250 ms by the player
) {
companion object {
val Empty = QueueUiState(emptyList(), playingId = null, positionMs = 0L)
}
}
@Composable
fun QueueScreen(state: QueueUiState, onPlay: (EpisodeId) -> Unit) {
LazyColumn {
items(state.episodes, key = { it.id.value }) { episode ->
EpisodeRow(
episode = episode,
isPlaying = episode.id == state.playingId,
onPlay = onPlay,
)
}
}
}
positionMs changes four times a second, so QueueScreen recomposes four times a second. That is expected. What we want is for each EpisodeRow to be skipped, because its inputs did not change. Whether that happens depends entirely on stability.
2. Stable vs unstable types: what the compiler infers
A type is stable when the compiler can be confident of two things: equals() gives consistent answers over time, and if a public property ever changes, Compose will be told.
The compiler does not run your code to find out. It reads the declaration and infers stability from its shape.
Two details are easy to miss:
- Function types are stable types, but each lambda instance is a different object. Stability says “comparison is trustworthy”, not “the value is the same”. We return to this in section 7.
-
Inference is recursive. A
data classof fiveval Strings is stable. Add one unstable property and the whole class flips.
That second point is exactly what bites our example. Episode has a val tags: List<String>, and everything that holds an Episode inherits the problem.
3. Why List, classes from other modules and var properties are treated as unstable
List<T> is an interface, not a promise
kotlin.collections.List is read-only, not immutable. The reference you hold might point to an ArrayList that another component is still appending to. The compiler cannot see what is behind the interface, so it takes the safe route and marks it unstable.
The failure mode in production looks like this:
// ViewModel
val state: StateFlow<QueueUiState> = repository.observeQueue()
.map { rows -> QueueUiState(rows.map { it.toEpisode() }, playingId = null, positionMs = 0) }
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), QueueUiState.Empty)
Each emission builds fresh Episode and List objects. Even if the contents are equal, an unstable parameter gives Compose no reason to believe that.
Classes from other modules
Stability information is recorded when a module is compiled with the Compose compiler. A model sitting in a pure-Kotlin :domain module, or in a third-party library, carries no such information, so the compiler assumes the worst, even when the class is a perfectly good immutable data class.
This is the sneakiest case because the class is flawless on inspection. The reports in section 6 are the only reliable way to catch it.
var properties
class Basket {
var total: Int = 0 // public mutable state the runtime cannot observe
}
A write to a plain var does not notify Compose, and equals() on the object may or may not reflect it. A public var makes the type unstable unless the property is backed by Compose state (for example var total by mutableIntStateOf(0)), in which case changes are observable and the type is treated as stable.
4. Fixes: immutable collections, @Stable / @Immutable, and stability configuration files
Fix 1: use immutable collections in UI state
import kotlinx.collections.immutable.ImmutableList
import kotlinx.collections.immutable.persistentListOf
import kotlinx.collections.immutable.toImmutableList
@Immutable
data class Episode(
val id: EpisodeId,
val title: String,
val tags: ImmutableList<String>,
)
@Immutable
data class QueueUiState(
val episodes: ImmutableList<Episode>,
val playingId: EpisodeId?,
val positionMs: Long,
) {
companion object {
val Empty = QueueUiState(persistentListOf(), playingId = null, positionMs = 0L)
}
}
// Map once, at the boundary between domain and UI:
private fun DomainEpisode.toEpisode() = Episode(
id = EpisodeId(id),
title = title,
tags = tags.toImmutableList(),
)
Convert in the ViewModel or mapper, not inside a composable. A toImmutableList() call during composition allocates on every pass and defeats the purpose.
Fix 2: @Immutable and @Stable are promises
-
@Immutable: once built, no observable property will ever change. -
@Stable: the type may change, butequals()is consistent and every change is reported to Compose (typically throughmutableStateOf).
The compiler does not verify either one. That is the failure mode to respect:
@Immutable
class Playlist(val items: MutableList<Episode>) // do not do this
// Later, somewhere else:
playlist.items.add(newEpisode) // no recomposition, stale UI, a bug that survives code review
If you annotate a class whose contents can change behind Compose’s back, skipping will happily show old data. Use the annotation only when you control every write.
Fix 3: a stability configuration file for types you cannot annotate
For java.time types, library models, or classes in a module you do not want to depend on Compose, declare them stable in a text file:
// stability_config.conf
java.time.*
com.example.podcast.domain.**
com.example.podcast.network.Cursor
* matches one package level, ** includes sub-packages, and a fully qualified name targets one class. Register it in Gradle:
// build.gradle.kts (module with Compose)
composeCompiler {
stabilityConfigurationFiles.add(
rootProject.layout.projectDirectory.file("stability_config.conf")
)
}
This carries the same risk as @Stable: you are making a claim the compiler will not check, so only list types you know to be effectively immutable. The Compose compiler already treats kotlinx.collections.immutable types as stable, so they need no entry. If you would rather keep plain List in your models and accept the contract yourself, adding kotlin.collections.* to this file opts the standard collections in. A third option is a small @Immutable wrapper class around the list. Whichever route you pick, confirm the result in a compiler report.
Fix 4: reshape the model
Often the best fix is boring. Prefer val properties, update with copy(), and when a screen genuinely needs mutation, hold it in mutableStateOf rather than in a plain var.
5. Strong skipping mode: what it changes and what it doesn’t
Strong skipping relaxes the rules. It is on by default with the Compose compiler that ships with Kotlin 2.0.20 and later. If you are on an older toolchain, it is an opt-in.
What it changes
- Composables with unstable parameters can now be skipped.
- Unstable arguments are compared by instance equality (
===). Stable ones still useequals(). - Lambdas are automatically memoized, keyed on the values they capture.
What it does not change
Instance comparison is weaker than structural comparison. Our ViewModel from section 3 still rebuilds every Episode on each emission, and new instances are never === to old ones. Strong skipping would not rescue that row; stability would.
// Strong skipping: skipped when the SAME instance comes back
EpisodeRow(episode = cachedEpisode, ...)
// Strong skipping: NOT skipped, new instance every pass
EpisodeRow(episode = episode.copy(), ...)
EpisodeRow(episode = Episode(id, title, tags.toList()), ...)
Three more limits worth remembering:
- Mutating an object in place is still invisible to Compose.
- Unstable types remain unstable in the compiler reports, so reports remain useful.
- Composables that return a value, and ones you mark
@NonSkippableComposable, are still never skipped.
Strong skipping is a better safety net, not a reason to stop designing UI state as immutable data.
6. Reading compiler reports to find unstable parameters
Do not guess; ask the compiler. Enable report output:
// build.gradle.kts
composeCompiler {
reportsDestination = layout.buildDirectory.dir("compose_compiler")
metricsDestination = layout.buildDirectory.dir("compose_compiler")
}
Build a release variant (debug builds can distort results), then open <module>-composables.txt. A function you hoped would skip might read:
restartable fun TagRow(
unstable tags: List<String>
stable onTagClick: Function1<String, Unit>
)
Under classic skipping, the absence of skippable plus an unstable parameter is your diagnosis. With strong skipping enabled, functions are labeled skippable even with unstable parameters, so the signal moves to the parameter lines: an unstable entry still tells you the argument will be compared by identity.
Then open <module>-classes.txt:
unstable class Episode {
stable val id: EpisodeId
stable val title: String
unstable val tags: List<String>
<runtime stability> = Unstable
}
This tells you which field poisoned the class. A practical triage loop:
- Sort the composables report for unstable parameters on hot paths (list items, anything under a frequently changing state).
- Trace each to its class in the classes report.
- Fix the field, rebuild, and confirm the line flipped to
stable.
Also check -module.json for a quick count of skippable versus restartable composables, which is handy as a trend line in CI.
7. Lambdas: remembered vs re-created, and rememberUpdatedState
A lambda that captures values is an object. Without memoization, each recomposition of the parent can produce a new one, which a child compares as a changed parameter.
@Composable
fun QueueRoute(viewModel: QueueViewModel) {
val state by viewModel.state.collectAsStateWithLifecycle()
// Classic mode: a new lambda capturing `viewModel` on every pass.
// Strong skipping memoizes this for you.
QueueScreen(state = state, onPlay = { id -> viewModel.play(id) })
}
If you are not using strong skipping, remember it with the right key:
val onPlay = remember(viewModel) { { id: EpisodeId -> viewModel.play(id) } }
Forgetting the key (remember { ... }) is a classic bug: the lambda keeps the first viewModel forever.
rememberUpdatedState: long-lived effects, fresh callbacks
Sometimes you want the opposite: an effect that keeps running while the callback it ends with can change. Restarting the effect to pick up the new lambda would reset a timer.
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.rememberUpdatedState
import kotlinx.coroutines.delay
import kotlin.time.Duration
@Composable
fun SleepTimerBanner(
timeout: Duration,
onExpired: () -> Unit,
) {
val latestOnExpired by rememberUpdatedState(onExpired)
LaunchedEffect(timeout) {
delay(timeout) // relative delay, so wall-clock changes cannot skew it
latestOnExpired() // always the most recent callback, no effect restart
}
}
Keying the effect on onExpired instead would cancel and restart the delay whenever the parent supplied a new lambda, and the timer would never finish.
8. When not to optimize
Stability work has a cost: annotations that can lie, config files to maintain, mapping layers to write. Spend it where it pays.
- Measure first. Use Layout Inspector’s recomposition counts, then a Macrobenchmark on the scroll or animation that actually janks. A composable that recomposes 40 times but costs microseconds each is not your problem.
-
Leaf composables that are cheap, such as a single
Text, rarely justify any effort. - Screens that change rarely do not benefit from perfect skipping.
-
Hot paths do: items in a
LazyColumn, anything beneath a state that updates many times a second, and expensive layouts. -
Prefer structural fixes over escape hatches. Pushing a changing value down to the composable that reads it (or reading it in a lambda such as
Modifier.graphicsLayer { }) often beats any stability annotation.
A reasonable policy for a team: use immutable UI state by default, keep strong skipping on, add a stability config for the few foreign types you rely on, and look at reports only when a measured regression sends you there.
Checklist
- UI state classes use
valand immutable collections. - Foreign types are covered by
stability_config.confor wrapped in a UI model. -
@Immutable/@Stableappear only where you control every write. - Reports are generated on demand, and you read the classes file, not just the composables file.
- Optimization follows a measurement, not a hunch.
Skipping is not magic. It is a comparison the compiler is willing to make only when you have given it reasons to trust the answer. Give it those reasons where it matters, and leave the rest alone.
📱 Go Beyond Using Jetpack Compose
If you’re building on Android, understanding what happens under the hood separates developers who use Compose from those who master it. I highly recommend “Mastering Jetpack Compose Internals”. It’s a deep, architecture-first walkthrough of the composition tree, the slot table, snapshot state, and the runtime that powers modern Android UI — capped off with a full case study building a real app called Mosaic.
- E-book: Available on Google Play
- Kindle Edition: Available on Amazon
- Topmate: Available on Topmate
- Also available in Paperback & Hardcover
Originally published on Medium.







Top comments (0)