Thinking in Compose: Composable Functions and the Three Phases

You have built many Compose screens by now, but you may still catch yourself thinking "how do I change the text of that label?" That question belongs to the old way of building Android UIs. Compose asks a different question: "what should the screen look like for this state?" Once that shift clicks, everything else in Compose becomes predictable.

This lesson is the foundation for the Jetpack Compose for Android developers course (the official programme at https://developer.android.com/courses/jetpack-compose/course). It covers Thinking in Compose, Composable functions, Write your first Compose app (the Compose basics codelab) and Compose phases. The next five lessons (38 to 41 and 43) continue with layouts, lazy lists, theming, animation and interoperability, and the Jetpack Compose programme's later pathways return in lessons 54 to 59.

By the end you will be able to:

• Explain declarative versus imperative UI, and why Compose is declarative.
• Describe recomposition, and why composable functions must be fast, idempotent and free of side effects.
• Explain the three phases of every frame: composition, layout and drawing.
• Use that knowledge to avoid unnecessary work (deferring state reads, lambda-based modifiers).
• Explain stability and skipping in simple terms.
• Build a small two-screen app (onboarding plus an expandable list) using only the basics.

Big idea: UI = f(state). The screen is a function of the data. When the data changes, Compose calls the function again.

• State (remember, mutableStateOf) and recomposition at a basic level (lessons 17 and 18).
• State hoisting and unidirectional data flow (lesson 24).
• Kotlin lambdas and trailing-lambda syntax (lesson 12).
• @Composable functions and @Preview (lessons 15 and 16).

The old way: imperative

With the older View system you built an object tree of views, then mutated each view by calling methods:

// View-system style (imperative); not Compose
val label = findViewById<TextView>(R.id.label)
val button = findViewById<Button>(R.id.button)
button.setOnClickListener {
 count++
 label.text = "Clicked $count times"
 if (count >= 5) {
 button.isEnabled = false
 label.setTextColor(Color.RED)
 }
}

You must remember to update every affected view in every code path. Add a third widget and a fourth rule, and it is easy to forget one, leaving the UI inconsistent with the data. These are among the most common bugs in classic apps.

The new way: declarative

In Compose you describe the UI for the current state and let the framework work out what changed:

@Composable
fun ClickCounter() {
 var count by remember { mutableIntStateOf(0) }
 Column {
 Text(
 text = "Clicked $count times",
 color = if (count >= 5) Color.Red else Color.Unspecified
 )
 Button(onClick = { count++ }, enabled = count < 5) {
 Text("Click me")
 }
 }
}

There is no "update the label" code. The click changes count; Compose recomposes the function with the new value; the text, the colour and the enabled flag are all derived from the same variable in one place. They cannot disagree.

Composable functions

A composable function is a function annotated @Composable that emits UI into a tree rather than returning it. Calling Text("Hi") does not draw anything immediately; it tells the Compose runtime "there should be a Text here".

The conventions you should follow:

Compose may call your composable many times, in any order, even on different threads, and may skip calls that it knows are unnecessary. To make that safe, a composable must behave like a pure function of its inputs.

A bad composable

var totalClicks = 0 // shared variable outside Compose
@Composable
fun BadCounter(onClick: () -> Unit) {
 totalClicks++ // side effect during composition!
 Text("Composed $totalClicks times")
 Button(onClick = onClick) { Text("Tap") }
}

totalClicks++ runs each time the function runs, which is not the same as each time the user taps. Compose might call BadCounter several times for a single frame, or skip it entirely, so the number is meaningless, and it also produces unpredictable behaviour when composition runs on several threads.

Where side effects belong

Side effects belong in event handlers (onClick, run when the user acts) or inside effect APIs that run at well-defined moments:

@Composable
fun GoodCounter(onClick: () -> Unit) {
 Text("Tap the button")
 Button(onClick = {
 onClick() // a side effect in an event handler: fine
 }) { Text("Tap") }
}

For effects that must happen as the screen appears or when a value changes (loading data, starting a timer, subscribing), use LaunchedEffect, DisposableEffect and SideEffect, covered in lesson 55. For now remember: the body of a composable only describes UI.

Do not read hidden mutable state

A composable that reads a plain var instead of Compose State will not recompose when it changes:

@Composable
fun Broken() {
 var count = 0 // ordinary variable
 Button(onClick = { count++ }) {
 Text("Clicked $count times") // never updates on screen
 }
}

Compose only knows to re-run code when it reads a snapshot state object such as mutableStateOf. And even with mutableStateOf, writing var count = mutableIntStateOf(0) without remember would reset to 0 on every recomposition, because the function body runs from the top each time. That is why remember { mutableIntStateOf(0) } exists: it stores the value in the composition so it survives recomposition.

When a state value changes, Compose finds the composables that read that value and re-runs only those, and only as much as needed.

@Composable
fun Dashboard() {
 var count by remember { mutableIntStateOf(0) }
 Column {
 Header() // does not read count
 CounterText(count) // reads count, so it recomposes
 Footer() // does not read count
 Button(onClick = { count++ }) { Text("Add") }
 }
}

When count changes, CounterText(count) gets a new argument and re-runs. Header() and Footer() take no changing inputs, so Compose skips them: it reuses the previous result. Skipping is what makes Compose fast.

When can Compose skip?

A composable can be skipped if all its parameters are unchanged and stable. Roughly:

• Unchanged: the new value is equals() the old one (for primitives, strings and data classes with equal fields).
• Stable: the type is guaranteed to tell Compose when it changes. Primitives, String, function types and classes with only stable val properties (and Compose State) are stable.

Types the compiler cannot prove stable include classes with var properties and the standard collection interfaces List, Set and Map, because the compiler cannot know whether the object behind a List is mutable. Recent Compose compiler versions have strong skipping mode enabled by default, which relaxes this: composables with unstable parameters can also be skipped when the instances are the same object (identity equal), and lambdas are remembered automatically. If you target an older compiler, you may need to use immutable collections or the @Immutable or @Stable annotations. You will measure this properly with the Layout Inspector's recomposition counts in lesson 44 and learn performance rules in lesson 59. For now:

• Prefer immutable data classes (val only) for UI state, as you have been doing.
• Pass the smallest data a composable needs, not a huge object.
• Do not worry about skipping for ordinary screens; measure before optimising.

Keep recomposition scopes small

Recomposition happens at the level of the composable (more precisely, the nearest enclosing restartable function or lambda) that reads the state. If you read a fast-changing value high in the tree, a large subtree re-runs. Reading it in a small child composable limits the work. We will exploit this in the next section.

Every time Compose produces a frame, it goes through three phases:

        state changes (e.g. count++, scroll offset)
                     |
                     v
 +-----------------------------------------------+
 | 1. COMPOSITION   What to show?                |
 |    Runs your @Composable functions,           |
 |    builds / updates the UI tree.              |
 +-----------------------------------------------+
                     |
 +-----------------------------------------------+
 | 2. LAYOUT        Where to put it?             |
 |    Measures each node (size), then places it  |
 |    (x, y). Parent passes constraints down,    |
 |    child reports size up.                     |
 +-----------------------------------------------+
                     |
 +-----------------------------------------------+
 | 3. DRAWING       How does it look?            |
 |    Draws every node onto a canvas,            |
 |    pixels reach the screen.                   |
 +-----------------------------------------------+

The same three words describe a house: decide what rooms there are (composition), decide where each wall and room goes (layout), paint and furnish (drawing).

Phase 1: Composition

Runs the composable functions you wrote and produces the tree of UI nodes. This is where Text("Clicked $count times") is evaluated. Reading a State here subscribes that scope to changes.

Phase 2: Layout

Two steps, applied to the tree from the top down and the bottom up:

1. Measure: a parent gives each child constraints (minimum and maximum width and height). The child measures itself within those constraints and reports a size. Children are measured once (a rule that makes layouts fast, unlike the older View system where nested layouts could measure repeatedly).
2. Place: once all sizes are known, the parent places each child at an (x, y) position.

You will experiment with constraints and modifier order in lesson 38.

Phase 3: Drawing

Each node draws itself onto a canvas in order, parents first, then children on top. Modifier.background, drawBehind, graphicsLayer and Canvas participate here.

Why the phases matter: skip the earlier ones

Each phase reads state independently. If a state read happens only in the layout phase, a change to that state re-runs layout and drawing but not composition. If it happens only in the drawing phase, only drawing re-runs. That is a big performance lever, and it is how smooth animations work.

Consider moving a box horizontally based on a fast-changing scroll offset.

Slow: state read during composition

@Composable
fun SlowBox(scrollOffset: State<Int>) {
 Box(
 Modifier.offset(x = scrollOffset.value.dp) // read in composition
 ) { Text("Hello") }
}

Reading scrollOffset.value as a function argument happens during composition, so every change recomposes the function, then lays out and draws again: all three phases, many times a second.

Fast: defer the read to the layout phase

import androidx.compose.foundation.layout.offset
import androidx.compose.ui.unit.IntOffset
@Composable
fun FastBox(scrollOffset: State<Int>) {
 Box(
 Modifier.offset { IntOffset(x = scrollOffset.value, y = 0) } // lambda: read in layout
 ) { Text("Hello") }
}

The offset { } overload that takes a lambda reads the state inside the layout phase. When the value changes, only layout and drawing re-run; composition is skipped. Many modifiers come in a "lambda" flavour for exactly this reason:

The rule of thumb: for values that change on every frame (animations, scrolling, dragging), read them as late as possible, in a lambda. For values that change only on a user's tap, the ordinary form is fine and clearer. Do not rewrite everything; do this where profiling or an animation demands it (lessons 41 and 59).

Backwards writes

A related pitfall: never write to a state after you have read it in the same composition. For example, reading count and then setting count++ inside the composable body (not inside an event handler) creates an endless recomposition loop. Compose logs a warning about a "backwards write". Changes to state belong in callbacks and effects.

This is the Compose basics codelab from the programme, rebuilt with our own code. The app has an onboarding screen with a Continue button, then a list of greetings whose items expand with an animation. It uses only what you have learned.

Create an Empty Activity project named Basics (package com.example.basics).

The structure

MyApp
 +-- if (shouldShowOnboarding) OnboardingScreen(onContinueClicked)
 +-- else Greetings(names)
        +-- LazyColumn
              +-- Greeting(name)   (expandable card)

Step 1: The entry point with hoisted state

package com.example.basics
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.animation.animateContentSize
import androidx.compose.animation.core.Spring
import androidx.compose.animation.core.spring
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.ElevatedButton
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
class MainActivity : ComponentActivity() {
 override fun onCreate(savedInstanceState: Bundle?) {
 super.onCreate(savedInstanceState)
 setContent {
 MaterialTheme {
 Surface(modifier = Modifier.fillMaxSize()) {
 MyApp()
 }
 }
 }
 }
}
@Composable
fun MyApp(modifier: Modifier = Modifier) {
 var shouldShowOnboarding by rememberSaveable { mutableStateOf(true) }
 Surface(modifier) {
 if (shouldShowOnboarding) {
 OnboardingScreen(onContinueClicked = { shouldShowOnboarding = false })
 } else {
 Greetings()
 }
 }
}

shouldShowOnboarding lives in MyApp, the lowest common ancestor that needs it, and is saved with rememberSaveable so rotation does not send the user back to the welcome screen. OnboardingScreen is stateless: it receives a callback and does not know how the flag is stored. This is state hoisting (lesson 24) in miniature. (For a real "show once ever" onboarding you would save the flag in DataStore, lesson 35.)

Step 2: The onboarding screen

@Composable
fun OnboardingScreen(
 onContinueClicked: () -> Unit,
 modifier: Modifier = Modifier
) {
 Column(
 modifier = modifier.fillMaxSize(),
 verticalArrangement = Arrangement.Center,
 horizontalAlignment = Alignment.CenterHorizontally
 ) {
 Text("Welcome to the Basics Codelab!")
 Button(
 modifier = Modifier.padding(vertical = 24.dp),
 onClick = onContinueClicked
 ) {
 Text("Continue")
 }
 }
}
@Preview(showBackground = true, widthDp = 320, heightDp = 320)
@Composable
fun OnboardingPreview() {
 MaterialTheme { OnboardingScreen(onContinueClicked = {}) }
}

Step 3: The expandable greeting card

@Composable
fun Greeting(name: String, modifier: Modifier = Modifier) {
 Card(modifier = modifier.padding(vertical = 4.dp, horizontal = 8.dp)) {
 CardContent(name)
 }
}
@Composable
private fun CardContent(name: String) {
 var expanded by rememberSaveable { mutableStateOf(false) }
 Row(
 modifier = Modifier
 .padding(12.dp)
 .animateContentSize(
 animationSpec = spring(
 dampingRatio = Spring.DampingRatioMediumBouncy,
 stiffness = Spring.StiffnessLow
 )
 )
 ) {
 Column(
 modifier = Modifier
 .weight(1f)
 .padding(12.dp)
 ) {
 Text(text = "Hello,")
 Text(
 text = name,
 style = MaterialTheme.typography.headlineMedium
 )
 if (expanded) {
 Text(
 text = "Composem ipsum color sit lazy, padding theme elit, sed do bouncy. ".repeat(4)
 )
 }
 }
 ElevatedButton(onClick = { expanded = !expanded }) {
 Text(if (expanded) "Show less" else "Show more")
 }
 }
}

Notice how expanded belongs to each card: because it is created with remember inside CardContent, every card in the list has its own independent flag. Expanding one does not expand the others.

In a long list, rememberSaveable state is stored against the item's position in the composition. In a LazyColumn, scrolling an item away and back keeps rememberSaveable values (plain remember would reset them when the item leaves the composition). Lesson 39 explains keys, which make this robust when the list changes.

Step 4: The list

@Composable
fun Greetings(
 modifier: Modifier = Modifier,
 names: List<String> = List(1000) { "$it" }
) {
 LazyColumn(modifier = modifier.padding(vertical = 4.dp)) {
 items(items = names) { name ->
 Greeting(name = name)
 }
 }
}
@Preview(showBackground = true, widthDp = 320)
@Composable
fun GreetingsPreview() {
 MaterialTheme { Greetings() }
}

List(1000) { "$it" } creates a thousand strings, "0" to "999". A Column would struggle; LazyColumn composes only what is visible (lesson 21). Run the app: tap Continue, scroll, expand a card (watch the springy animation from animateContentSize), rotate the phone (the expanded cards and the screen choice survive).

What you just used

Run the app, then open Tools > Layout Inspector (lesson 44 covers it fully). In the options, enable Show recomposition counts. Tap "Show more" on one card and watch the counts: only that card's subtree recomposes, not its neighbours. That is skipping in action, and an early taste of how you will verify performance with data instead of guesses.

Mistake #1: Side effects in the body. What happens: actions repeat unpredictably (extra network calls, duplicate analytics). The fix: event handlers or effect APIs (lesson 55).

Mistake #2: mutableStateOf without remember. What happens: the state resets on every recomposition. The fix: remember { mutableStateOf(...) }, or rememberSaveable.

Mistake #3: A plain var. What happens: the UI never updates. The fix: Compose state.

Mistake #4: Doing heavy work in a composable. What happens: janky scrolling and animation. The fix: compute in the ViewModel, or use remember(key) { ... } or derivedStateOf.

Mistake #5: Reading fast-changing state in composition. What happens: unnecessary recompositions. The fix: the lambda versions of modifiers (offset { }, graphicsLayer { }) or drawBehind.

Mistake #6: Writing state while composing (backwards write). What happens: an infinite loop warning. The fix: write state only in callbacks and effects.

Mistake #7: Making every composable depend on the whole UI state. What happens: everything recomposes on any change. The fix: pass only what each composable needs.

Mistake #8: Forgetting the modifier parameter. What happens: callers cannot position or size your composable. The fix: modifier: Modifier = Modifier as the first optional parameter, applied to the root element.

Mistake #9: Prematurely optimising. What happens: complicated code with no measured benefit. The fix: measure with the Layout Inspector and the profiler first (lessons 44 and 59).

Question 1. What is the difference between declarative and imperative UI?

Question 2. Why must a composable be idempotent and free of side effects?

Question 3. What are the three phases of a frame?

Question 4. Why is Modifier.offset { } with a lambda faster than Modifier.offset(x = ...) for a rapidly changing value?

Question 5. What does it mean for Compose to skip a composable?

Go deeper: official resources

• Jetpack Compose for Android developers (course)
• Pathway 1: Compose essentials: Thinking in Compose, Composable functions, Write your first Compose app, Compose phases.
• Jetpack Compose basics codelab
• Compose architecture