Jetpack Compose in panels

Updated: Oct 1, 2025

Overview

Jetpack Compose is a modern, declarative toolkit for building native Android UIs. It simplifies UI development on Android with powerful tools and intuitive Kotlin APIs.

Spatial SDK supports Jetpack Compose and other UI frameworks. Use Jetpack Compose within Spatial SDK to build 2D panels. Preview and edit them in real time using the Live Edit feature.

There are two ways to create panels in a 3D scene with Jetpack Compose:

View-based: Lightweight and performant

Activity-based: More flexible and powerful, comes with a performance cost

Create Android views directly with Jetpack Compose

Use Jetpack Compose directly within an Android view for better performance. This approach eliminates additional activities, conserves resources, and enhances overall performance.

Gradle dependency

Add the meta-spatial-sdk-compose library to your Gradle dependencies. This library contains the ComposeFeature class with helper functions that simplify using Jetpack Compose in Spatial SDK.

  // Add ComposeFeature in the immersive activity
  override fun registerFeatures(): List<SpatialFeature> {
    return listOf(..., ComposeFeature())
  }

Register a view-based panel with Jetpack Compose

The meta-spatial-sdk-compose library includes a special PanelRegistration class called ComposeViewPanelRegistration.

class ComposeViewPanelSettings(
    registrationId: Int,
    composeViewCreator: (entity: Entity, context: Context) -> ComposeView,
    settingsCreator: (entity: Entity) -> PanelSettings,
    panelSetupWithComposeView: (ComposeView, PanelSceneObject, Entity),
)

This simple example shows how to use ComposeViewPanelRegistration to register a panel and display a ComposeView with your custom Jetpack Compose UI.

override fun registerPanels(): List<PanelRegistration> {
  return listOf(
      ComposeViewPanelRegistration(
          R.id.welcome_panel,
          composeViewCreator = { _, ctx ->
            ComposeView(ctx).apply { setContent { WelcomePanel() } }
          },
          settingsCreator = { _ ->
            UIPanelSettings()
          },
      )
  )
}

@Composable
fun WelcomePanel() {
  Text("Hello from Compose!")
}

Spawn the panel using the Entity.createPanelEntity API:

Entity.createPanelEntity(
    R.id.welcome_panel,
    Transform(Pose(Vector3(0.0f, 0.0f, -1.0f))),
)

Create Android Activity with Jetpack Compose

Create standalone activities that use Jetpack Compose for more complex UIs that need full activity lifecycle management. This approach provides greater flexibility and access to Android’s activity features. Use this when you need features like activity-specific navigation, complex state management, or integration with other activity-based libraries.

Define the Android Activity that displays Jetpack Compose UI

First, define your Jetpack Compose UI.

@Composable
fun MessageCard(name: String) {
    Text(text = "Hello $name!")
}

Create the activity for the panel and set the content to the Jetpack Compose UI.

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material3.Text

class MyComposeActivity : ComponentActivity() {
  override fun onCreate(savedInstanceBundle: Bundle?) {
    super.onCreate(savedInstanceBundle)
    setContent { MessageCard("Meta Spatial SDK") }
  }
}

Define the activity in your AndroidManifest.xml and include the tag android:allowEmbedded="true". This allows the activity to be embedded into a panel.

Register and spawn the panel

After creating the activity with Jetpack Compose, register the panel using PanelRegistration:

override fun registerPanels(): List<PanelRegistration> {
  return listOf(
      ActivityPanelRegistration(
        registrationId = R.id.activity_panel,
        classIdCreator = { MyComposeActivity::class.java },
        settingsCreator = { UIPanelSettings() }
      )
  )
}

Spawn the panel using the Entity.createPanelEntity API:

Entity.createPanelEntity(
    R.id.activity_panel,
    Transform(Pose(Vector3(0.0f, 0.0f, -1.0f))),
)

Performance considerations

Jetpack Compose UI code runs on the main thread in your Spatial SDK application. Expensive UI operations can slow your scene’s responsiveness.

Use the release version of your app. Debug builds run Jetpack Compose code significantly slower.

Review the Jetpack Compose Performance documentation.

Run UI code on a separate thread by placing your Activity in a separate process. See Android processes and threads for details. This approach requires inter-process communication (IPC) between activities, so use it carefully.

Design guidelines

Did you find this page helpful?