You don't understand stability in Compose

This article took some parts from the course Advanced Compose I am currently working on. This course dives deep into Compose topics that are important yet often misunderstood by Compose developers.

Why stability matters?

import androidx.compose.foundation.*
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.text.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.*
import androidx.compose.ui.draw.*
import androidx.compose.ui.unit.*
import androidx.compose.ui.window.*
import androidx.compose.ui.graphics.*
import androidx.compose.ui.graphics.vector.*
import kotlinx.browser.document
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
import androidx.compose.animation.*
import androidx.compose.animation.core.*
import androidx.compose.foundation.lazy.grid.*
import androidx.compose.foundation.shape.*
import androidx.compose.ui.text.font.*
import androidx.compose.ui.text.style.*
import androidx.compose.ui.text.input.*
import androidx.lifecycle.compose.*
import androidx.compose.ui.layout.*

//sampleStart
@Composable
fun MutableListSample() {
    val list by remember { mutableStateOf(mutableListOf<String>()) }

    Column {
        // Button click will do nothing visible, because it will not trigger recomposition
        Button(onClick = { list.add("Item${list.size}") }) {
            Text("Add Item")
        }
        Column {
            list.forEach {
                Text(it)
            }
        }
    }
}
//sampleEnd

@OptIn(ExperimentalComposeUiApi::class)
fun main() {
    ComposeViewport(document.body!!) {
        Box(modifier = Modifier.size(300.dp, 600.dp)) {
            MutableListSample()
        }
    }
}

@Stable
class MyCustomState {
    var value1 by mutableStateOf(0)
    var value2 by mutableStateOf("ABCD")
}

1. Immutable types: String, Int, PersistentList… - which are always safe to pass down.
2. Stable types: State<T>, function types, state objects… - which are mutable, but also safe to pass down.
3. Unstable types: mutable classes, lists, view models… - which are mutable and generally unsafe to pass down, however most of them can be observed in a stable way (for example, by collecting StateFlow to State using collectAsStateWithLifecycle).

Different behavior for unstable types, and Strong Skipping Mode

• For stable / immutable parameter types, Compose use equality checks (conceptually == so equals).
• For unstable parameter types, Compose uses reference checks (conceptually ===).

1. composable function parameters,
2. keys in remember blocks,
3. keys in effect blocks.

// Poor practice
@Composable
fun UserList(users: MutableList<User>) {
    // ...
}

@Composable
fun MyComposable(unstableObject: Unstable, stableObject: Stable) {
    val lambda = {
        use(unstableObject)
        use(stableObject)
    }
}

// Under the hood, this is equivalent to:
@Composable
fun MyComposable(unstableObject: Unstable, stableObject: Stable) {
    val lambda = remember(unstableObject, stableObject) {
        {
            use(unstableObject)
            use(stableObject)
        }
    }
}

What is unstable?

Debugging stability

Basic types

// Poor practice
fun UserItem(userState: State<User>) {
    val user by userState
    Text(user.name)
}

// Good practice 
fun UserItem(user: User) {
    Text(user.name)
}

// Good practice
fun UserItem(userProvider: () -> User) {
    Text(userProvider().name)
}

Function types

@Composable
fun UserManagementScreen(viewModel: MainViewModel = injectViewModel()) {
    val uiState = viewModel.uiState.collectAsStateWithLifecycle()
    
    UserList(
        uiStateProvider = { uiState.value }, // Changes only if uiState changes (most likely never)
        onUserClick = { viewModel.onUserClick(it) }, // New function only if viewModel changes (most likely never)
        onRefresh = viewModel::onAccept, // Works just like lambda above
    )
}

@Composable
fun UserItem(
    user: User, 
    onUserClicked: (User) -> Unit,
) {
    Row {
        Text(user.name)
        Button(onClick = { onUserClicked(user) }) {
            Text("Click me")
        }
    }
}

Collections

Stability configuration

composeCompiler {
    stabilityConfigurationFiles = 
        listOf(rootProject.layout.projectDirectory.file("stability_config.conf"))
}

// Consider collections stable
kotlin.collections.List
kotlin.collections.Set
kotlin.collections.Map
// Consider LocalDateTime stable
java.time.LocalDateTime

Custom classes stability

class MultipleAnswerQuestionUi(
    val question: String,
    val answers: PersistentList<AnswerUi>,
)

class AnswerUi(
    val text: String,
    val isSelected: Boolean,
    val isCorrect: Boolean,
)

composeCompiler {
    reportsDestination = layout.buildDirectory.dir("compose_compiler")
    metricsDestination = layout.buildDirectory.dir("compose_compiler")
}

// In app_release-composables.txt
restartable skippable fun UserScreen(
  unused unstable uiState: UserUiState
)

// In app_release-classes.txt
unstable class UserUiState {
  stable val isLoading: Boolean
  unstable val user: User?
  stable val error: String?
  <runtime stability> = Unstable
}
unstable class User {
  stable val id: Int
  stable val name: String
  unstable val tags: List<String>
  <runtime stability> = Unstable
}

Interface stability

Summary

• Type stability (since String Skipping Mode) decides how objects are compared when Compose decides it should recompose composable, recalculate remember block or recall side effect. Stable types are compared with == and unstable with ===.
• It is recommended to use stable types in Compose. Unstable type in a complex class can cause lots of unnecessary recompositions, leading to performance issues.
• String, Int (and other number), Boolean, State<T> and function types are stable. List, Map, Set and mutable classes are unstable. PersistentList, PersistentMap, PersistentSet are stable.
• Stability can be tracked with Compose Stability Analyzer or stability report. We can also enforce it with annotations @Stable and @Immutable or with stability configuration.