Getting Started with Remote Compose: A Practical Example

In the previous part, we covered what Remote Compose is and why it exists. Now let’s build something real — a simple UI document, serialize it, and render it in an Android app.

Alpha warning: androidx.compose.remote is currently 1.0.0-alpha07. The API surface is still changing. Code in this post reflects the alpha07 state.

Project Setup

Dependencies

Add the Remote Compose modules to your project. For a typical Android app that both creates and plays documents locally (useful for testing or widget scenarios), you need both sides:

1
// build.gradle.kts (app module)
2
dependencies {
3
    // Creation side — generates the document
4
    implementation("androidx.compose.remote:remote-creation:1.0.0-alpha07")
5
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha07")
6

7
    // Player side — renders the document
8
    implementation("androidx.compose.remote:remote-player-core:1.0.0-alpha07")
9
    implementation("androidx.compose.remote:remote-player-view:1.0.0-alpha07")
10

11
    // Preview support during development
12
    debugImplementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha07")
13
}

minSdk: Remote Compose requires minSdk 23 (as of alpha04). If your project targets lower, enable core library desugaring — the library uses Java 11 APIs since alpha06.

1
// build.gradle.kts (app module)
2
android {
3
    compileOptions {
4
        isCoreLibraryDesugaringEnabled = true
5
    }
6
}
7
dependencies {
8
    coreLibraryDesugaring("com.android.tools.desugar_jdk_libs:2.1.4")
9
}

The Creation Side: Building a Document

The creation API mirrors Compose composables but operates in a different composition scope — the RemoteApplier. Functions here don’t draw to a Canvas; they build a serializable UI tree.

Think of it as writing a template that will be frozen and shipped to a device.

1
import androidx.compose.remote.creation.RemoteCompose
2
import androidx.compose.remote.creation.compose.RemoteColumn
3
import androidx.compose.remote.creation.compose.RemoteText
4
import androidx.compose.remote.creation.compose.RemoteButton
5
import androidx.compose.remote.creation.compose.RemoteSpacer
6
import androidx.compose.remote.creation.compose.remoteModifier
7
import androidx.compose.remote.creation.compose.fillMaxWidth
8
import androidx.compose.remote.creation.compose.padding
9

10
fun buildWelcomeDocument(): ByteArray {
11
    return RemoteCompose.capture {
12
        RemoteColumn(
13
            modifier = remoteModifier()
14
                .fillMaxWidth()
15
                .padding(24f)
16
        ) {
17
            RemoteText(
18
                text = "Hello from the server!",
19
                style = RemoteTextStyle.titleLarge()
20
            )
21

22
            RemoteSpacer(height = 12f)
23

24
            RemoteText(
25
                text = "This UI was defined outside the app and rendered locally by the player runtime.",
26
                style = RemoteTextStyle.bodyMedium()
27
            )
28

29
            RemoteSpacer(height = 24f)
30

31
            RemoteButton(
32
                onClick = RemoteAction.log("button_clicked"),
33
                modifier = remoteModifier().fillMaxWidth()
34
            ) {
35
                RemoteText(text = "Tap me")
36
            }
37
        }
38
    }
39
}

RemoteCompose.capture { ... } runs the creation block and returns a ByteArray — the serialized document. You can write this to disk, send it over HTTP, or pass it through IPC.

Key constraint: You cannot call regular @Composable functions inside a RemoteCompose.capture { } block. The RemoteApplier enforces this at compile time.

Simulating a Server Response

In a real production app, the document would come from a backend service. For this example, let’s simulate it locally with a coroutine:

1
// In a ViewModel or repository
2
class DocumentRepository {
3
    suspend fun fetchWelcomeDocument(): ByteArray {
4
        // Simulate network delay
5
        delay(300)
6
        // In production: val response = httpClient.get("/ui/welcome")
7
        //                return response.body()
8
        return buildWelcomeDocument()
9
    }
10
}

The document is just bytes. You can cache it, store it in a database, or version it however your backend works.

The Player Side: Rendering in a Fragment

remote-player-view provides RemoteComposePlayerView — a View (not a Composable) that accepts a document and renders it. You can embed it in any XML layout or in a Compose UI via AndroidView.

Option A: Using it in XML Layout

1
<FrameLayout
2
    xmlns:android="http://schemas.android.com/apk/res/android"
3
    android:layout_width="match_parent"
4
    android:layout_height="match_parent">
5

6
    <androidx.compose.remote.player.view.RemoteComposePlayerView
7
        android:id="@+id/remote_player"
8
        android:layout_width="match_parent"
9
        android:layout_height="wrap_content" />
10

11
    <ProgressBar
12
        android:id="@+id/loading"
13
        android:layout_width="wrap_content"
14
        android:layout_height="wrap_content"
15
        android:layout_gravity="center"
16
        android:visibility="gone" />
17

18
</FrameLayout>

1
class RemoteFragment : Fragment(R.layout.fragment_remote) {
2

3
    private val viewModel: RemoteViewModel by viewModels()
4

5
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
6
        super.onViewCreated(view, savedInstanceState)
7

8
        val player = view.findViewById<RemoteComposePlayerView>(R.id.remote_player)
9
        val loading = view.findViewById<ProgressBar>(R.id.loading)
10

11
        viewLifecycleOwner.lifecycleScope.launch {
12
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
13
                viewModel.documentState.collect { state ->
14
                    when (state) {
15
                        is DocumentState.Loading -> {
16
                            loading.isVisible = true
17
                            player.isVisible = false
18
                        }
19
                        is DocumentState.Success -> {
20
                            loading.isVisible = false
21
                            player.isVisible = true
22
                            player.setDocument(state.bytes)
23
                        }
24
                        is DocumentState.Error -> {
25
                            loading.isVisible = false
26
                            // Show error UI
27
                        }
28
                    }
29
                }
30
            }
31
        }
32
    }
33
}

Option B: Embedding in Compose via AndroidView

If your app is fully Compose-based:

1
@Composable
2
fun RemoteScreen(documentBytes: ByteArray?) {
3
    if (documentBytes == null) {
4
        Box(
5
            modifier = Modifier.fillMaxSize(),
6
            contentAlignment = Alignment.Center
7
        ) {
8
            CircularProgressIndicator()
9
        }
10
        return
11
    }
12

13
    AndroidView(
14
        factory = { context ->
15
            RemoteComposePlayerView(context).apply {
16
                layoutParams = ViewGroup.LayoutParams(
17
                    ViewGroup.LayoutParams.MATCH_PARENT,
18
                    ViewGroup.LayoutParams.WRAP_CONTENT
19
                )
20
            }
21
        },
22
        update = { playerView ->
23
            playerView.setDocument(documentBytes)
24
        },
25
        modifier = Modifier.fillMaxWidth()
26
    )
27
}

Handling Remote Actions

Buttons and interactive elements in the document can emit RemoteActions — named events that the host app handles. The document declares what to emit; the player surfaces them:

1
// When building the document:
2
RemoteButton(
3
    onClick = RemoteAction.named("navigate_to_details", mapOf("id" to "42"))
4
) { ... }
5

6
// In the host app, set an action listener on the player view:
7
player.setActionListener { action ->
8
    when (action.name) {
9
        "navigate_to_details" -> {
10
            val id = action.params["id"]
11
            findNavController().navigate(
12
                RemoteFragmentDirections.toDetails(id)
13
            )
14
        }
15
        "button_clicked" -> {
16
            analytics.track("remote_button_tapped")
17
        }
18
    }
19
}

This keeps business logic in the app where it belongs, while the document controls layout and content.

The ViewModel

1
sealed interface DocumentState {
2
    data object Loading : DocumentState
3
    data class Success(val bytes: ByteArray) : DocumentState
4
    data class Error(val message: String) : DocumentState
5
}
6

7
class RemoteViewModel(
8
    private val repository: DocumentRepository
9
) : ViewModel() {
10

11
    private val _documentState = MutableStateFlow<DocumentState>(DocumentState.Loading)
12
    val documentState: StateFlow<DocumentState> = _documentState.asStateFlow()
13

14
    init {
15
        loadDocument()
16
    }
17

18
    private fun loadDocument() {
19
        viewModelScope.launch {
20
            _documentState.value = DocumentState.Loading
21
            runCatching { repository.fetchWelcomeDocument() }
22
                .onSuccess { _documentState.value = DocumentState.Success(it) }
23
                .onFailure { _documentState.value = DocumentState.Error(it.message ?: "Unknown error") }
24
        }
25
    }
26

27
    fun retry() = loadDocument()
28
}

What This Enables

With this setup, the UI that renders in RemoteComposePlayerView can be updated by changing what the server returns — without any app update. The user sees a different layout, different text, different button, on their next launch.

Practical use cases:

A/B testing UI variants without deploying new builds
Feature flags that show or hide UI sections
Widgets and tiles (this is how Glance will work once migrated)
Dynamic onboarding flows that the product team can iterate on independently

What It Can’t Do Yet

Being alpha07, there are real limitations:

No arbitrary composables — you can only use what remote-creation exposes. No custom composables from your codebase.
No ViewModel scope — the document is stateless. Any stateful logic lives in the host app and is communicated via RemoteAction.
No navigation — the player renders a single document; navigation between screens is the host app’s responsibility.
API breaks frequently — every alpha release has changed something. Don’t build production infrastructure on this until beta.

What to Watch For

The trajectory is clear. As the public API surface stabilizes and Glance migration progresses, Remote Compose will become the standard way to build widgets, lock screen components, Wear OS tiles, and cross-process UIs. The pattern you learn here carries forward.

Keep an eye on:

remote-creation-jvm — the server-side JVM module that will unlock true backend document generation
Glance’s migration roadmap to remote-player
The alpha → beta transition, which will signal API stability

Full Example on GitHub

The complete working example (ViewModel, Fragment, document builder, action listener) is available in the project’s examples/compose-remote-demo directory.