skip to content

In Jetpack Compose, what makes a composable restartable or skippable, and how does recomposition use those two properties when state changes?

level: middleimportance: must knowfreq 66%

answer

  1. where re-execution may start
  2. when a call may be passed over
  3. nearest scope that read the state
  4. inline layouts are not scopes
  5. non-Unit return never skips

basics

~20 s

Restartable means a composable is a scope where recomposition can start re-executing; skippable means Compose may pass over a call whose parameters equal last time's. A state change re-runs the nearest restartable scope that read it and skips unchanged skippable calls inside.

solid answer

~40 s

Initial composition runs your composables and records the Composition; recomposition is the only way to update it. The Compose compiler tags each composable. **Restartable** means it can be the entry point for re-execution: when a `State` it read changes, Compose invalidates the nearest such scope and re-runs it rather than the whole screen. Inline layouts such as `Column`, `Row` and `Box` are not scopes, so a read inside their content invalidates the enclosing function. **Skippable** means that during a pass Compose can skip the call when every argument equals its previous value. A function is not eligible for skipping if it returns a non-`Unit` value, is annotated `@NonRestartableComposable` or `@NonSkippableComposable`, or, without strong skipping, has an unstable required parameter. With strong skipping, the default since Kotlin 2.0.20, every restartable composable is skippable.

go deeper

for a junior

Know that recomposition re-runs the parts of the UI affected by changed state rather than the whole screen, and that unchanged calls can be skipped.

for a middle

Explain restartable versus skippable, the nearest-scope rule, and why inline layouts like Box are not scopes. Name the three reasons a function is not eligible for skipping.

for a senior

Read a composables report and say from its tags why a function re-runs. Restructure code so a frequently changing read sits in a narrow scope.

for a principal

Judge when skip and restart machinery is worth its generated code, and when a team should leave a cheap composable unskippable instead of chasing skippability everywhere.

## Composition and recomposition When Jetpack Compose runs your composables for the first time, the **initial composition**, it records the calls you made in a tree called the **Composition**. Each call is identified by its **call site**, the place in the source where it appears, plus the order of execution when the same call site runs several times in a loop. When app state changes, Compose schedules a **recomposition**: it re-executes the composables that may have changed and updates the Composition. The documentation is explicit that recomposition is the *only* way to modify a Composition after it exists. A composable's lifecycle is therefore short: it enters the Composition, is recomposed zero or more times, and leaves. ## Restartable: where recomposition can start The Compose compiler marks functions with tags. A **restartable** composable serves as a **recompose scope**: a point where Compose can start re-executing code after state changes. 1. While a scope runs, Compose records which `State` objects it reads. 2. When one of those objects changes, Compose invalidates the **nearest enclosing restartable scope** that read it. 3. On the next frame it re-runs that scope, plus the calls inside it that cannot be skipped, not the whole screen. Composable functions and composable lambdas you pass to other composables can each be a scope, which is why a state change often re-runs one small lambda and nothing else. The trap is **inline** composables. `Column`, `Row` and `Box` are declared `inline`, so their content lambda is copied into the caller and is **not** a scope of its own. A state read inside `Box { ... }` invalidates the function that contains the `Box`, and everything in it that cannot be skipped runs again. Extracting the reading code into its own composable creates a narrower scope. ## Skippable: when a call can be passed over A **skippable** composable can be passed over during recomposition if all its arguments are equal to their previous values. Compose compares **stable** parameters with `equals()`; how **unstable** ones are treated depends on strong skipping (below). A composable function is **not eligible for skipping** when: - it has a non-`Unit` return type; - it is annotated `@NonRestartableComposable` or `@NonSkippableComposable`; - a required parameter is of an unstable type, unless strong skipping is on. Types the compiler treats as stable without annotation include primitives, `String`, enums, function types (lambdas) and Compose's `MutableState`. Interfaces are generally treated as not stable, and the standard collection types `List`, `Set` and `Map` are inferred unstable because their implementation could be mutable. ## Strong skipping changes the last rule Since **Kotlin 2.0.20** the Compose compiler enables **strong skipping** by default. With it, every restartable composable is skippable, whatever its parameters; unstable parameters are compared by instance (`===`) and stable ones by `equals()`. Non-restartable composables stay unskippable. On older toolchains, an unstable parameter meant the function was never skipped. ## Opting out on purpose | Annotation | What it does | When it fits | |---|---|---| | `@NonRestartableComposable` | no restart or skip code is generated | tiny functions that just call another composable | | `@NonSkippableComposable` | restartable, but never skipped | opting one function out of strong skipping | | `@ReadOnlyComposable` | no group is generated around the body | functions that only read, such as a theme value; the body must make read-only calls only | Compose's own foundation and Material libraries have added `@NonRestartableComposable` to simple overloads, where restart machinery costs more than it saves. ## Reading the compiler's verdict The Compose compiler reports, switched on with `reportsDestination` in the `composeCompiler` block, write a `composables.txt` per module. Each line starts with the tags the compiler assigned: ```plaintext restartable skippable scheme("[androidx.compose.ui.UiComposable]") fun SnackCollection( stable snackCollection: SnackCollection stable index: Int = @static 0 ) ``` A line that says `restartable` without `skippable` is a function Compose never skips, even with unchanged inputs. Reading these tags is the first step whenever a composable recomposes more than you expect.

  • In Jetpack Compose, why can a state read inside Box's content re-run more code than expected?
    `Box` is an inline function, so its content lambda is not a recompose scope. A state read there invalidates the enclosing composable function, which re-runs along with any calls inside it that cannot be skipped. Moving the read into a small composable of its own gives Compose a narrower scope to restart.
  • When does @NonRestartableComposable make sense on a composable?
    On small functions that just call another composable, have little logic and are unlikely to be invalidated themselves. The annotation stops the compiler generating restart and skip code. Compose's libraries use it on simple forwarding overloads; on a function that reads state it would push invalidation up to the caller.
  • How does Compose tell apart several calls to the same composable from one call site?
    By call site plus execution order. In a loop, inserting an item at the top shifts every later call, so instances recompose with new inputs and their effects restart. Wrapping the body in `key(item.id) { ... }` ties each instance to the item instead of its position.

  • Every state change recomposes the whole screen from the root.
  • Column, Row and Box each create their own recomposition scope.
  • Any composable can be skipped, whatever it returns.
  • A skipped composable is removed from the screen.
  • Without strong skipping, a List parameter is compared with equals and skipped.

Assumes Compose 1.12 with Kotlin 2.0.20 or newer, where strong skipping is on by default and every restartable composable is skippable.