State and remember

The counter that will not count

Here is a perfectly reasonable-looking screen. It is also completely broken.

1@Composable
2fun BrokenCounter() {
3    // This does not work. Read on.
4    var rolls = 0
5
6    Column {
7        Text(text = "Rolls: $rolls")
8        Button(onClick = { rolls++ }) {
9            Text(text = "Roll")
10        }
11    }
12}

It compiles. It installs. You tap the button and the screen says Rolls: 0. You tap it twenty more times. Rolls: 0.

Nothing you know so far explains that, and guessing at it is where most people's first week goes. So let us take it apart properly, because the answer is the foundation of everything else in Compose.

Problem one: nobody told Compose anything changed

Remember what a composable really is: an ordinary function. BrokenCounter() runs once, produces a description of a screen, and finishes. It is not sitting there watching a variable.

When you tap the button, rolls++ runs and the number in memory really does become 1. But there is no wire from that variable to the screen. Compose has no idea anything happened, so it never re-runs BrokenCounter, so the Text that was drawn with 0 is still the Text on the glass.

Compose only re-runs a function — a process called recomposition — when a value it knows how to watch changes. Ordinary Kotlin variables are not watchable.

The fix is a special kind of holder:

val rolls = mutableStateOf(0)

mutableStateOf gives you a MutableState<Int>: a small box with a .value inside it. It is not the number — it is a box holding the number, and Compose watches boxes.

• When a composable reads rolls.value while it runs, Compose quietly writes down "this function depends on that box".
• When anything writes to rolls.value, Compose looks up every function that read it and schedules them to run again.

That is the whole subscription mechanism. Reading is subscribing.

Problem two: local variables do not survive the re-run

Suppose we only fix problem one:

1@Composable
2fun StillBroken() {
3    // Still wrong, in a new and more interesting way.
4    val rolls = mutableStateOf(0)
5
6    Column {
7        Text(text = "Rolls: ${rolls.value}")
8        Button(onClick = { rolls.value++ }) {
9            Text(text = "Roll")
10        }
11    }
12}

Now the tap does trigger a recomposition. And the screen still says Rolls: 0. Worse — it flickers to 1 on some devices and snaps straight back.

Here is why, and it is the bit that clicks late for most people:

When Compose re-runs your function, it runs the whole function. Line one included.

Line one is val rolls = mutableStateOf(0). So the re-run throws away the box that held 1 and builds a brand new box holding 0. The screen is redrawn from a value that was reset half a millisecond ago.

This is not Compose being strange. It is just how functions work. Every local val and var inside any function is created fresh on every call — that has always been true, in every language you will ever use. What is new is that your function is called again, by something other than you, possibly sixty times a second.

remember: a pigeonhole that survives the re-run

val rolls = remember { mutableStateOf(0) }

remember takes a lambda and does something very specific:

• The first time this line runs, it calls your lambda, keeps the result in a slot inside Compose's own memory, and returns it.
• Every time after that, it ignores the lambda completely and hands back the value already in the slot.

So the box is built exactly once. Every later run of the function gets the same box, still holding whatever it was holding. The hand-washing no longer matters, because the note is in a pigeonhole now.

Two things follow that are worth saying out loud:

• remember on its own does not cause redraws. remember { 0 } gives you a value that survives but that nothing watches.
• mutableStateOf on its own does not survive. It gives you a watchable box that gets rebuilt every run.

You almost always want both. That is why the two words appear together so often that they look like a single keyword. They are not.

The by delegate: the version you will actually write

rolls.value everywhere gets noisy fast. Kotlin has a feature for exactly this, and Compose is built to use it:

1var rolls by remember { mutableStateOf(0) }
2
3Text(text = "Rolls: $rolls")
4// ...
5rolls++

No .value anywhere. rolls now reads and writes like a plain Int.

by is Kotlin's property delegate keyword — the same one from Lesson 1.18. It means: this name does not store anything itself; hand every read and every write to that object over there. Reading rolls calls the box's getValue; assigning to rolls calls its setValue. Compose's subscription still happens, because underneath it is still .value.

Two rules come with it:

1. Use var, not val. val rolls by remember { ... } compiles but you can never assign to it — Val cannot be reassigned. With by, the var/val choice describes whether you may assign, and you almost always want to.
2. Two extra imports. androidx.compose.runtime.getValue and androidx.compose.runtime.setValue. Miss them and you get one of the ugliest error messages in Android; it is first in the Error Doctor below, so you will recognise it.

Three ways of writing the same thing, for reference:

The middle one is the house style of this course and of the Compose documentation. The third is handy when you want to pass the setter to a child composable — you will meet it again in Part 4.

Putting it together

1@Composable
2fun RollCounter() {
3    var rolls by remember { mutableStateOf(0) }
4    var die by remember { mutableStateOf(5) }
5
6    Column(
7        modifier = Modifier
8            .fillMaxSize()
9            .padding(24.dp),
10        verticalArrangement =
11            Arrangement.spacedBy(12.dp),
12        horizontalAlignment =
13            Alignment.CenterHorizontally
14    ) {
15        Text(text = "You rolled: $die")
16        Text(text = "Rolls this game: $rolls")
17        Button(
18            onClick = {
19                die = Random.nextInt(1, 7)
20                rolls++
21            }
22        ) {
23            Text(text = "Roll")
24        }
25    }
26}

Turning the phone sideways loses everything

Try it: run the counter, tap up to 7, then rotate the phone. Rolls this game: 0.

Rotation destroys and rebuilds the Activity — Lesson 2.2's lifecycle, in the flesh. Compose's memory of your remember slots goes with it, because those slots lived inside the screen that just died.

For small values there is a drop-in fix:

var rolls by rememberSaveable { mutableStateOf(0) }

rememberSaveable does everything remember does, and additionally writes the value into the same saved-state bundle Android already uses to restore a rotated screen. Rotate now and the count is still 7.

It has limits, and they are worth knowing before you rely on it:

• The value must be something Android knows how to store: Int, Long, Float, Boolean, String, arrays and lists of those, or a Parcelable. Your own data class needs extra work — Part 4 shows the two ways.
• It is for small things. A saved bundle is not a database; a big list belongs in Room, not in rememberSaveable.
• It does not replace a ViewModel. Once a screen has more than two or three pieces of state and any real logic, the state should move out of the composable entirely. That is Lesson 4.1 and 4.2, and it is the single biggest step up in this course.

For now: remember by default, rememberSaveable when losing the value on rotation would actually annoy someone.

Remembering with a key

One more form, because you will need it in Part 5:

1val shuffled = remember(seed) {
2    (1..6).shuffled()
3}

remember(seed) means "keep this, unless seed changes — if it does, throw it away and build it again". Without a key, remember holds on forever. With one, you get a value that rebuilds exactly when its input does.