In Jetpack Compose, what does SideEffect guarantee that code in a composable body does not, and what did 1.12's keyed overload add?
answer
- publish to non-Compose objects
- after a successful apply
- every recomposition, or per key
- no cleanup block
basics
~20 sSideEffect runs its block after every recomposition that applies successfully, on the apply dispatcher; body code can run for compositions that are discarded. Compose runtime 1.12 added keyed SideEffect overloads that run only when a key changes.
solid answer
~40 s`SideEffect { controller.samplingMode = mode }` publishes Compose state to an object Compose does not manage. The runtime records the block and runs it when the composition completes and applies, on the apply dispatcher, after `DisposableEffect` and other `RememberObserver` callbacks, in composition order. Writing the assignment straight into the body is unsafe because composition may run without being applied, so the outside object could be updated for UI that never appears. The keyless form runs after every successful recomposition of its caller. Compose runtime 1.12.0 added overloads taking one to four keys or a vararg: `SideEffect(mode) { ... }` runs on first composition and then only when `mode` changes, which replaces a `LaunchedEffect` or `DisposableEffect` whose scope or `onDispose` went unused. `SideEffect` has no cleanup; if the change must be undone, use `DisposableEffect`.
go deeper
Recall that SideEffect pushes Compose values into objects Compose does not manage, and that it runs after each successful recomposition rather than once.
Explain why body code is unsafe for this, what apply means, and how the 1.12 keyed overload narrows when the block runs.
Pick between SideEffect, DisposableEffect and LaunchedEffect by whether the change suspends, must be undone, or should run only on change.
When raising the Compose version to 1.12, look for empty onDispose blocks and non-suspending LaunchedEffects that keyed SideEffect can replace.
## What SideEffect is for Some objects live outside Compose but must reflect Compose state: a non-Compose controller that samples a sensor at a rate chosen on screen, a map view's overlay, an analytics client's user property, a View embedded in the hierarchy. You want each recomposition's final values to reach that object, and you want nothing to leak if a composition is thrown away. `SideEffect` is the effect for this: **publish state outward, no coroutine, no cleanup**. ## Why not write the assignment in the body Composition is not a commitment. The runtime may compose a change and then discard it, compose parts in an order you do not expect, or run a composable function more often than the UI is applied. Code in the body therefore: - may run for a composition that is **never applied**, leaving the outside object describing UI that does not exist; - runs **during** composition, interleaved with other composables' work, rather than after the tree is consistent. `SideEffect` defers the block. The runtime records it during composition and runs it only **when the composition completes successfully and applies its changes**. ## The guarantees the runtime documents 1. The block runs on the composition's **apply dispatcher** (the UI thread on Android). 2. Appliers never run concurrently with themselves, with each other, with applying changes to the tree, or with `RememberObserver` callbacks. 3. `SideEffect` blocks run **after** all `DisposableEffect` and `RememberObserver` callbacks for that apply. 4. Multiple side effects run in the order they appear in the composition (an in-order traversal). 5. The keyless overload runs after **every** recomposition of its caller; there is no "first time only". ## The keyed overloads in 1.12 Before Compose runtime 1.12, "run this assignment once, and again only when `mode` changes" had no direct API. Teams wrote `LaunchedEffect(mode) { controller.samplingMode = mode }` (a coroutine that never suspends) or a `DisposableEffect(mode)` with an empty `onDispose`, which the guide calls a smell. Compose runtime **1.12.0** (stable since August 2026; it first appeared in 1.12.0-alpha02) added `SideEffect(key1) { }`, overloads with two, three and four keys, and a vararg form. The block runs on the first composition and then only when a key **differs from its previous value** (compared with `equals()`), still after a successful apply. | API | Runs | Coroutine | Cleanup | |---|---|---|---| | `SideEffect { }` | After every successful recomposition of the caller | No | No | | `SideEffect(key) { }` (1.12+) | First composition, then when a key changes | No | No | | `LaunchedEffect(key) { }` | Launches on enter and on key change | Yes | Cancelled on key change or leave | | `DisposableEffect(key) { }` | On enter and on key change | No | `onDispose` before re-run and on leave | A keyed call reads like this: ```kotlin @Composable fun CompassSampling(mode: SamplingMode, controller: SensorController) { // Runs on first composition, then only when mode changes. SideEffect(mode) { controller.samplingMode = mode } } ``` On 1.11 or earlier this call does not resolve, because only the keyless `SideEffect(effect)` exists there. Inside, the keyed overload is small: it asks the composer whether the key `changed()` since the last composition and records the block only if so. The vararg form also compares the number of keys, so calling it with a different count of keys counts as a change. Nothing is remembered beyond the key values themselves, which is why the keyed form costs less than an effect object. ## Choosing among them - **Pure publication of the latest value** (an assignment, a setter): `SideEffect`, keyed if the setter is expensive or must not repeat for equal values. - **The change must be reverted** when the composable leaves (restore a window flag, remove an overlay): `DisposableEffect`, because `SideEffect` has no hook for leaving. - **The work suspends** or runs over time: `LaunchedEffect`. ## Common mistakes - Using `SideEffect` to **start** work, such as a network request, which then fires after every recomposition. - Expecting `SideEffect` to run **once**: without keys it runs every time the caller recomposes. - Reading state inside `SideEffect` and expecting that read to **trigger** a recomposition: the block runs after composition, so its reads do not subscribe any recompose scope.
- In Jetpack Compose, in what order do SideEffect blocks and DisposableEffect setup run when one composition applies?The runtime dispatches remember-observer callbacks first, which include `DisposableEffect` setup and disposal, and runs `SideEffect` blocks after them. Among side effects, the order follows the composition hierarchy in an in-order traversal, so an earlier call in the tree runs first.
- In Jetpack Compose before 1.12, how did teams run a one-shot assignment only when a value changed?They used `LaunchedEffect(value) { ... }` with a block that never suspends, or `DisposableEffect(value)` with an empty `onDispose`. Both worked but paid for a coroutine or a cleanup hook they did not use; Compose runtime 1.12 added keyed `SideEffect` overloads for exactly this case.
- SideEffect runs once, when the composable first enters composition
- Assigning to an outside object in the composable body is equivalent to SideEffect
- SideEffect runs on a background thread after the frame is drawn
- SideEffect has an onDispose block for undoing its change
- Keyed SideEffect has been available since Compose 1.0
Assumes Compose runtime 1.12; the keyed SideEffect overloads were added in 1.12.0 and do not exist in 1.11 or earlier.