A senior engineer’s field guide to Remote Compose: the mental model, the Kotlin that fits it, and the bugs that show up when you forget which clock your code runs on.
🧠 TL;DR (Too Long; Didn’t Read)
- Remote Compose lets you write UI with Compose-style APIs in your app, then record it as a compact document that a player in another process (an App Widget host, a Wear OS surface) renders and animates on its own.
- Your Kotlin runs at record time, to produce a document. It never runs inside the host. (Recomposition can still happen while recording; the release notes mention an
EnforceCleanRecompositionflag, so don't assume exactly one pass.) Anything that must change later, on the host, has to be expressed as remote state, remote modifiers, or declarative actions, not asif, string templates, or lambdas. - Most production bugs fall into one pattern: a value was frozen at record time when the author assumed it was live.
- Treat the publish loop (data → snapshot → document → host) as a small, boring, well-gated pipeline.
1. The problem Remote Compose is solving
A home-screen widget is your UI, but it does not live in your process. A launcher or a watch face draws it. Historically that boundary forced a lowest-common-denominator vocabulary: a fixed set of views and a bag of PendingIntents.
Remote Compose attacks the boundary differently. Instead of shipping instructions for a fixed set of views, you ship a small description of a UI, together with the state bindings and actions it needs, and let the host’s player do the work of drawing it and reacting to touches.
The three blocks are worth memorizing, because every design decision later hangs off them:
-
Create. Your app runs
@RemoteComposablefunctions and records the result: layout, remote state declarations, and actions. - Transport. The document moves from your process to whoever displays it. When your data changes, you can record and send a new one.
- Play. The host’s player lays out the document, handles input, mutates UI state, and runs animations, all without a round trip to your app.
Two benefits follow directly: documents stay small, and interactions that the player can resolve itself never wake your process. The official guide offers a helpful analogy: it resembles a server handing a page to a browser, after which the browser handles interactions locally rather than re-asking the backend. Hold on to that image, because it also predicts the failure modes. A page that was rendered with yesterday’s number in it still says yesterday’s number.
2. A running example: the parcel tile
To keep things concrete, I’ll use one widget throughout: a parcel tile that shows a carrier, a short list of checkpoints, an estimated arrival, and a tap target that expands or collapses the checkpoint list.
It’s a deliberately ordinary widget, and that’s the point. It has three kinds of data, and the rest of this post is about telling them apart:
Start with the model, and start with Kotlin that makes illegal states hard to express:
@Immutable
data class ParcelTileModel(
val carrier: String,
val headline: String,
val checkpoints: List<Checkpoint>,
val stage: Stage,
) {
@Immutable
data class Checkpoint(val label: String, val reached: Boolean)
sealed interface Stage {
data object Packed : Stage
data class InTransit(val hubsPassed: Int) : Stage
data object OutForDelivery : Stage
data class Delivered(val signedBy: String?) : Stage
}
}
Two idioms matter here. First, @Immutable plus data gives you cheap equality, which you will lean on in section 7 to avoid re-recording identical documents. Second, a sealed interface for stage lets the compiler enforce exhaustive handling wherever you map stage into structure.
3. Record time versus play time
This is the one idea to internalize. Your Kotlin does not run on the host. It runs while you produce the document. Everything in the document is either a fact about the world at that moment or a symbolic reference the player resolves later.
That is why standard control flow still works, but only for what you know right now:
import androidx.compose.remote.creation.compose.layout.RemoteColumn
import androidx.compose.remote.creation.compose.layout.RemoteComposable
import androidx.compose.remote.creation.compose.layout.RemoteText
import androidx.compose.remote.creation.compose.state.rs
import androidx.compose.runtime.Composable
@RemoteComposable
@Composable
fun CheckpointList(checkpoints: List<ParcelTileModel.Checkpoint>) {
RemoteColumn {
// Fine: the list is known at record time, so we unroll it into the document.
checkpoints.forEach { cp ->
RemoteText(text = cp.label.rs) // .rs turns a record-time String into a RemoteString
}
}
}
The loop is legitimate because the checkpoint list is a recording-time fact. What you cannot do is loop over something the player owns, because nobody on the host is running your forEach.
How the two models compare
The guide contrasts standard Compose with Remote Compose across several domains. Here is the same comparison, reorganized by the question you will actually ask yourself while coding:
A few rows deserve extra commentary for senior readers:
-
Side effects. In normal Compose,
LaunchedEffectis a first-class citizen. In Remote Compose, composition runs in your app to create the document; coroutine effects can't drive UI on the host, unless your integration deliberately keeps a composition open. Default to assuming they cannot. Even if you do keep a composition open, the host only changes when a new document is recorded and transported. - Lifetime. Standard Compose needs a live process to recompose and render. A Remote Compose document replays on the host without calling back into your app, which is the whole value proposition for surfaces where your process may be asleep.
- State. Standard state holds live values in your memory. Remote state declarations are symbolic: they declare a binding the player manages.
4. Symbolic state and the things you cannot read
State is where intuition fails first. In Remote Compose you declare state through factory functions such as rememberMutableRemoteInt, rememberMutableRemoteFloat, and rememberMutableRemoteString. What you get back is not a value; it is a reference. Your code cannot inspect it during composition, because the player, not your process, stores and updates it.
So this is a trap:
// ❌ Intent: "show the checkpoints only when expanded".
// Reality: this Kotlin Boolean is captured when the document is recorded.
@RemoteComposable
@Composable
fun ParcelTileWrong(model: ParcelTileModel, isExpandedFromApp: Boolean) {
RemoteColumn {
RemoteText(text = model.headline.rs)
if (isExpandedFromApp) { // decided once, at record time
CheckpointList(model.checkpoints)
}
}
}
The branch is evaluated when the document is created. Tapping the tile on the host can never re-evaluate it. The fix is to hold the toggle as remote state and branch with a layout that the player evaluates:
import androidx.compose.remote.creation.compose.layout.RemoteStateLayout
import androidx.compose.remote.creation.compose.state.rememberMutableRemoteBoolean
// ✅ The player owns the toggle and picks the branch.
@RemoteComposable
@Composable
fun ParcelTile(model: ParcelTileModel) {
// Initial value passed positionally; confirm the parameter name in your release.
val expanded = rememberMutableRemoteBoolean(false)
RemoteColumn {
RemoteText(text = model.headline.rs)
RemoteStateLayout(currentState = expanded) { isExpanded ->
if (isExpanded) CheckpointList(model.checkpoints) else CollapsedSummary(model)
}
}
}
@RemoteComposable
@Composable
private fun CollapsedSummary(model: ParcelTileModel) {
RemoteText(text = model.carrier.rs)
}
This one reads like ordinary Kotlin, so it deserves a careful look. RemoteStateLayout takes a currentState (a RemoteBoolean for two states, or a RemoteEnum for more) and a content lambda that receives a plain Boolean. The if inside the lambda is not reading live state. The reference describes the layout as composing both possible states into the document and letting the player handle visibility and transitions based on currentState. So the Kotlin if runs at record time, once per branch, to build both subtrees, and the player decides which is visible. That is the difference between the wrong example and this one.
Text deserves its own warning
Standard Kotlin string interpolation evaluates once, when the document is created. If you write a template that includes a remote value, you do not get live text. You get the text of whatever that expression produced at record time. The documented remedy is to pass a RemoteString to RemoteText so the player can resolve it. A plain Kotlin String you already know at record time becomes a RemoteString with the .rs extension, which is what the code above uses for static text. For text that must change on the host, use a remote string state such as rememberMutableRemoteString instead of a template.
Styling follows the same rule
Dynamic styling on the host does not re-run composition. You feed remote state directly into modifiers, for instance a background that takes a remote color, so the player restyles in place. If you find yourself wanting a Kotlin if around a modifier, ask whether the condition is a recording-time fact (fine) or a player-time value (use remote state).
5. Actions: a tap is data, not a callback
In standard Compose, a click handler is a lambda that runs in your process. The host cannot run your app’s lambdas, so Remote Compose replaces them with declarative actions that you attach with RemoteModifier.clickable(action).
The choice is a question of where the work must happen:
-
valueChangeupdates remote state directly on the host. This is the right tool for our expand/collapse toggle, and it never touches your app. -
pendingIntentActionhands off to your app, for work only your process can do, such as opening a detail screen. -
hostActionhands off to the host. -
combinedActionruns several actions from a single click.
A sketch for the tile. RemoteModifier.clickable takes a single Action (the varargs form was removed in alpha09), and valueChange takes the state to update and the new value, so a toggle reads naturally:
import android.app.PendingIntent
import androidx.compose.remote.creation.compose.action.pendingIntentAction
import androidx.compose.remote.creation.compose.action.valueChange
import androidx.compose.remote.creation.compose.modifier.RemoteModifier
import androidx.compose.remote.creation.compose.modifier.clickable
@RemoteComposable
@Composable
fun ParcelTile(model: ParcelTileModel, openDetail: PendingIntent) {
val expanded = rememberMutableRemoteBoolean(false)
// 1) Local and instant: flip the toggle on the host. Never calls your app.
// `!expanded` is a symbolic remote expression, not a Kotlin Boolean; the same
// valueChange(state, !state) pattern appears in the official RemoteSplitSwitchButton sample.
val toggle = valueChange(expanded, !expanded)
// 2) Hand off to your app. pendingIntentAction is itself a @Composable,
// so create it during composition, not inside a click handler.
val showDetail = pendingIntentAction(openDetail)
RemoteColumn(modifier = RemoteModifier.clickable(toggle)) {
RemoteText(text = model.headline.rs)
RemoteStateLayout(currentState = expanded) { isExpanded ->
if (isExpanded) CheckpointList(model.checkpoints) else CollapsedSummary(model)
}
RemoteText(
text = "Open details".rs,
modifier = RemoteModifier.clickable(showDetail),
)
}
}
If one tap must do both jobs, combine them. The release notes list a CombinedAction type and a combinedAction factory (exposed in alpha12), and the official guide names combinedAction. Confirm whether your release takes varargs or a list before you copy this:
// Shape to confirm against your release: combinedAction(toggle, showDetail)
RemoteModifier.clickable(combinedAction(toggle, showDetail))
A design rule I’ve found useful: prefer actions that stay in the player, and escalate to pendingIntentAction only when state or navigation genuinely lives in your process. Each escalation is a place where behavior depends on your app being reachable, which is precisely the coupling this architecture is trying to remove.
6. Layout that survives someone else’s screen
Because the host can resize, rotate, or re-compose the surface independently of your app, geometry cannot be a record-time constant.
Remote Compose gives you familiar containers (RemoteBox, RemoteRow, RemoteColumn) plus adaptive ones built for this exact problem: RemoteFitBox, RemoteCollapsibleRow, and RemoteCollapsibleColumn. Use RemoteMaterialTheme for the same color and typography hierarchy you'd expect from your design system, which keeps widgets visually consistent with the app.
For anything environmental, the rule from the guide is blunt: CompositionLocal providers such as LocalConfiguration or LocalDensity describe your local app environment at the moment of recording. They do not follow the host as it resizes or changes state. Reach for values the player resolves at runtime, such as the component's current size, RemoteConfiguration, or RemoteDensity.
For custom drawing and time-based animation, RemoteCanvas records drawing commands that the player executes on the host. Treat it like the rest of the model: the commands are recorded once; the player replays them.
7. The publish loop: keep it boring
Since your Kotlin only runs when you record, the pipeline that decides when to record becomes the real engineering surface. It should be small, cancellable, and impossible to turn into a storm.
Here is a version that fits the diagram. The recording call is injected because it depends on your surface; everything else is plain Kotlin and trivially testable:
// import kotlinx.coroutines.CancellationException (not java.util.concurrent's)
fun interface DocumentSink {
suspend fun publish(document: ByteArray)
}
class ParcelTilePublisher(
private val record: suspend (ParcelTileModel) -> ByteArray, // your surface-specific recorder
private val sink: DocumentSink,
private val log: (String, Throwable) -> Unit = { _, _ -> },
) {
suspend fun run(models: Flow<ParcelTileModel>) {
models
.distinctUntilChanged() // identical snapshots produce identical documents
.collectLatest { model -> // a newer model cancels stale recording work
try {
sink.publish(record(model))
} catch (e: CancellationException) {
throw e // never swallow cancellation
} catch (e: Exception) {
log("publish failed for stage=${model.stage}", e)
}
}
}
}
One contract to respect: run ParcelTilePublisher.run in a coroutine context that your surface's recording integration supports (for example, the one it documents for composition and snapshot work). collectLatest runs the lambda in the collector's context, so don't pick a dispatcher casually.
Why each line earns its place:
-
distinctUntilChanged()works because the model is an immutabledata class. If your upstream emits on every poll, this alone prevents most redundant documents. -
collectLatestdrops stale recording work when fresher data arrives. Recording an outdated tile only to overwrite it a moment later is wasted effort. -
Explicit
CancellationExceptionrethrow keeps structured concurrency intact. A blanketcatch (e: Exception)without that line is a classic way to build a publisher that can't be cancelled.
One more consideration if your transport crosses a process boundary: documents are described as compact, but “compact” is not “free”. Keep decisions that depend only on recording-time facts out of the player’s way, and don’t send what the host can compute from remote state it already has.
8. Failure modes in the wild
These are the failures I’d expect to see in code review and in production, derived from the model’s rules. The root cause is almost always the same sentence: “I assumed this was live, and it was frozen.”
8.1 The frozen label
Symptom: the text looks right the first time and never changes. Cause: interpolating a value into a Kotlin string. It is evaluated at record time. Fix: hand a RemoteString to RemoteText.
8.2 The dead branch
Symptom: the wrong variant of the UI is shown forever, or the UI ignores taps. Cause: a Kotlin if/when over a value the player owns. Your code can't read remote state during composition, so the branch was decided with whatever you had. Fix: model the variants as slots and switch with RemoteStateLayout.
8.3 Stale geometry
Symptom: the widget looks perfect at the size it was first recorded and wrong after the user resizes it. Cause: sizes derived from LocalDensity or LocalConfiguration, which describe the recording environment. Fix: use RemoteDensity, RemoteConfiguration, component size, and the adaptive containers.
8.4 The ghost effect
Symptom: a LaunchedEffect runs happily in your app, yet nothing on the host moves. Cause: effects run in the process doing the composing; they don't exist on the host. Fix: move time- and data-driven changes into remote state or animations that the player runs, or record and send a new document when your data changes. Keeping a composition open does not change that: the host still only sees new documents.
8.5 The silent click
Symptom: a tap does nothing, or only works while your process happens to be alive. Cause: a mental model of click lambdas. The host can’t run your code. Fix: attach an action. If the work is purely UI state, use valueChange so it never leaves the player.
8.6 The document storm
Symptom: battery drain, widget flicker, or burst updates after a sync. Cause: recording and sending on every emission from an upstream that re-emits equal values. Fix: the gate from section 7: immutable models, distinctUntilChanged, collectLatest.
8.7 Mixing in the wrong components
Standard Compose containers and the Remote* equivalents are not interchangeable. The guide is explicit that you should use Remote Compose components and RemoteModifier in place of their standard counterparts. Code that compiles because the names look alike but pulls in a non-remote primitive is a good candidate for a lint rule or a code-review checklist item.
8.8 One more I’d test for: version skew
This one is an inference, not something the guide states, so treat it as a test plan item rather than a documented behavior. The document is produced by one library and played by another, and the two ship on different schedules. A recording that uses newer features than the installed player supports is a risk worth validating on the oldest host you intend to support, before your users find it for you.
9. Testing without a host
Because the real logic lives in plain Kotlin, push as much as possible into pure functions:
internal fun ParcelTileModel.Stage.headline(): String = when (this) {
ParcelTileModel.Stage.Packed -> "Packed and waiting"
is ParcelTileModel.Stage.InTransit -> "In transit, $hubsPassed hubs passed"
ParcelTileModel.Stage.OutForDelivery -> "Out for delivery"
is ParcelTileModel.Stage.Delivered -> signedBy?.let { "Delivered, signed by $it" } ?: "Delivered"
}
This is a record-time decision, so a string template is exactly right here, and a plain unit test covers it with no Android dependencies. The same applies to the publisher in section 7: feed it a flowOf(...) and a fake DocumentSink, then assert how many documents were published. Reserve device or host-level testing for what only the player can answer: how the document renders, resizes, and responds to input.
10. A decision checklist
Before writing a line of Remote Compose, ask:
-
Does this value change after the document is delivered? If yes, it must be remote state, a remote modifier input, or a
RemoteString. -
Can the player resolve it alone? Prefer
valueChange; escalate topendingIntentActiononly when your process truly must act. -
Does geometry depend on the host? Use
RemoteDensity,RemoteConfiguration, and the adaptive containers. -
What triggers a new document? Gate it with immutable models and
distinctUntilChanged. - Which oldest host must I support? Test the document there.
Remote Compose rewards one habit above all others: before every expression, say out loud which clock it runs on. Code that runs at record time can be as expressive as Kotlin allows. Code that has to live on the host has to be something the player can carry.
Source
- Android Developers, Remote Compose concepts and architecture (Jetpack Compose, System capabilities): https://developer.android.com/develop/ui/compose/system/remote-compose
- Library release notes: https://developer.android.com/jetpack/androidx/releases/compose-remote
📱 New to Jetpack Compose? Start Here
If you’re coming from the classic Android View system — XML layouts, findViewById, RecyclerView adapters — and want a clear, no-jargon path into Jetpack Compose, I recommend "Learning Jetpack Compose: Your Practical Guide from the Android View System to Modern Declarative UI." Every chapter starts from something you already know and shows its Compose equivalent side by side, building up to a full capstone: a real Notes app. Once you're comfortable and want to go deeper — the Composition tree, recomposition internals, the runtime itself — "Mastering Jetpack Compose Internals" is the natural next step.
- E-book: Available on Google Play
- Kindle Edition: Available on Amazon
- Topmate: Available on Topmate
- Also available in Paperback & Hardcover
Originally published on Medium.







Top comments (0)