ViewModel — state that outlives the screen

Turn your phone sideways

Open Dice Duel. Play until somebody has 12 points. Now rotate the phone.

Both scores are zero.

Nothing crashed. No error appeared. Your code is not wrong. What happened is that Android did exactly what it always does when the screen shape changes: it destroyed your entire Activity and built a brand new one.

Every remember you wrote went with it. remember means "remember for as long as this screen exists", and the screen stopped existing.

This is called a configuration change, and rotation is only the most obvious one. Switching to dark mode does it. Changing the system font size does it. Changing the phone's language does it. Unfolding a folding phone does it twice.

What a ViewModel actually is

A ViewModel is an ordinary Kotlin class that extends ViewModel. That is the entire trick. What makes it special is not the class — it is who keeps hold of it.

When you ask for a ViewModel from a screen, Android does not hand you a new one each time. It looks in a store attached to the Activity, and:

• if one already exists, you get that same object back;
• if not, it creates one and files it in the store.

During a rotation, Android deliberately carries that store across to the new Activity. The screen is destroyed; the store is not. So the new screen asks for its ViewModel, gets the old object, and the scores are still there.

The ViewModel is finally thrown away when the screen goes for good — when the user presses Back out of it, or the Activity finishes. At that point Android calls onCleared() on it.

The smallest possible ViewModel

Here is Dice Duel's score, moved out of the composable entirely.

1package com.nativeworks.diceduel
2
3import androidx.compose.runtime.getValue
4import androidx.compose.runtime.mutableStateOf
5import androidx.compose.runtime.setValue
6import androidx.lifecycle.ViewModel
7
8class GameViewModel : ViewModel() {
9
10  var p1 by mutableStateOf(0)
11    private set
12
13  var p2 by mutableStateOf(0)
14    private set
15
16  var turn by mutableStateOf(1)
17    private set
18
19  fun award(points: Int) {
20    if (turn == 1) p1 += points else p2 += points
21    turn = if (turn == 1) 2 else 1
22  }
23
24  fun newGame() {
25    p1 = 0
26    p2 = 0
27    turn = 1
28  }
29}

Using it from a screen

Add one dependency, which Pocket Notes and Focus Flow both already have:

1implementation(
2  libs.androidx.lifecycle.viewmodel.compose
3)

Then ask for the ViewModel by giving it a default value:

1@Composable
2fun GameScreen(
3  vm: GameViewModel = viewModel()
4) {
5  ScoreBoard(p1 = vm.p1, p2 = vm.p2, turn = vm.turn)
6
7  DieFace(
8    value = die,
9    onRoll = { vm.award(Random.nextInt(1, 7)) }
10  )
11}

Two details worth noticing.

viewModel() is a default parameter value, not a line inside the body. That is deliberate: a test or a @Preview can pass in its own ViewModel with a pretend score, because the parameter is still just a parameter.

And this is hoisting from Lesson 4.1, carried one floor higher. ScoreBoard still takes plain numbers. It has no idea a ViewModel exists — which is why it stays previewable.

Doing slow work: viewModelScope

Every ViewModel comes with a coroutine scope built in, called viewModelScope. Work launched in it is cancelled automatically when the ViewModel is cleared.

That matters more than it sounds. A coroutine started in a composable and left running after the user leaves is a leak: it holds memory, and when it finishes it writes to a screen nobody is looking at. viewModelScope makes that impossible without you thinking about it.

Pocket Notes uses it everywhere it touches the database:

1fun delete(note: Note) {
2  viewModelScope.launch { repo.delete(note) }
3}

repo.delete is a suspend function — it may pause while the disk does its work. launch starts a coroutine that is allowed to pause. And if the user closes the app mid-delete, the scope is cancelled with it.

When the ViewModel needs a Context

Room needs a Context to open a database. But a ViewModel outlives the Activity, so storing an Activity in one is a memory leak — you would be holding a destroyed screen alive forever.

The safe way is AndroidViewModel, which hands you the Application object. The Application lives as long as the whole process, so keeping it is harmless.

1class NotesViewModel(
2  app: Application
3) : AndroidViewModel(app) {
4
5  private val repo = NotesRepository(
6    NotesDatabase.get(app).noteDao()
7  )
8}

That is the real first six lines of Pocket Notes' ViewModel. No dependency injection library, no extra dependency — which matters when your builds run on a phone.