Develop

Meta VR Layout SDK overview

Updated: Aug 27, 2026

Overview

The Meta VR Layout SDK adds spatial windows around the main window of a Standard Android app. Your app remains non-immersive, can coexist with other open apps, and keeps its existing activity and UI architecture. You do not need to adopt the Meta Spatial SDK entity-component-system architecture.

A cooking app with ingredient and timer panels arranged beside the main recipe window

Use the Layout SDK for tools, details, or controls that benefit from separate windows. Jetpack Compose and React Native share the same scene-and-window model and use fallback behavior when spatial placement is unavailable. Meta Spatial Simulator can model the feature during development, but verify final placement on a headset. Use Meta Spatial SDK when you need 3D objects or environment manipulation.

Add the Meta VR SDK BOM

The MetaVRX BOM keeps Maven artifacts from Meta VR SDKs for Android on compatible versions. Import the com.meta.metavrx:metavrx-bom artifact through Gradle’s platform() function, then omit versions from the individual artifacts managed by the BOM.

The Gradle examples use Kotlin DSL and a version catalog at gradle/libs.versions.toml. Add the BOM and Layout aliases:

[versions]
metavrx-bom = "1.2026.0.0"

[libraries]
metavrx-bom = { module = "com.meta.metavrx:metavrx-bom", version.ref = "metavrx-bom" }

# Jetpack Compose
metavrx-layout-compose = { module = "com.meta.metavrx.layout:layout-compose-compat" }
metavrx-layout-window-compose = { module = "com.meta.metavrx.layout:layout-window-compose-compat" }

# React Native
metavrx-layout-react = { module = "com.meta.metavrx.layout:layout-react-compat" }
metavrx-layout-window-react = { module = "com.meta.metavrx.layout:layout-window-react-compat" }

Set up Jetpack Compose

Declare the BOM, core Layout artifact, and window artifact in app/build.gradle.kts:

dependencies {
    implementation(platform(libs.metavrx.bom))
    implementation(libs.metavrx.layout.compose)
    implementation(libs.metavrx.layout.window.compose)
}

The Layout SDK is a compatibility library and does not declare a minimum Horizon OS version. On releases earlier than v207, it uses fallback behavior instead of creating spatial windows.

Call SpatialScene inside your activity’s setContent block. Content at the scene root remains in the main window. Pass your app theme through SpatialScene because spatial window compositions do not automatically inherit composition locals established outside the scene.

In your activity’s onCreate() method, add this setContent call and wrap your app UI in SpatialScene. AppTheme, MainContent, and ToolsPanel represent your app’s UI.

import metavrx.layout.compose.SpatialScene
import metavrx.layout.window.compose.SpatialWindow
import metavrx.layout.window.compose.state.WindowFallback

setContent {
    SpatialScene(theme = { content -> AppTheme { content() } }) {
        MainContent()
        SpatialWindow(
            key = "tools",
            fallbackStrategy = WindowFallback.Inline,
        ) {
            ToolsPanel()
        }
    }
}

Keep every SpatialWindow within the scene and give each window a unique, stable key.

Set up React Native

Use React 18.2 or later and React Native 0.85 or later. This setup requires a bare React Native project or an Expo project that preserves its generated native Android files.

If you use Expo Continuous Native Generation and regenerate native files with the following command, automate the Gradle setup below through a custom config plugin or Expo configuration. This includes the version catalog, BOM import, and native dependencies.

npx expo prebuild --clean

Install the base Layout and Layout Window JavaScript packages:

npm install @metavr/layout-compat @metavr/layout-window-compat

Both must be direct app dependencies so React Native discovers and links each package’s native registration and codegen schema during the Android build.

Declare the BOM and both native Layout artifacts in the Android app module’s build.gradle.kts:

dependencies {
    implementation(platform(libs.metavrx.bom))
    implementation(libs.metavrx.layout.react)
    implementation(libs.metavrx.layout.window.react)
}

The packages use standard React Native automatic linking. Do not register SpatialWindowPackage manually. The React Native AARs merge the required Meta VR OS SDK declarations and volumetric-window permission into your app manifest.

Wrap the spatial portion of the app once with SpatialSceneProvider. Give each SpatialWindow a unique, stable label.

The following fragment shows the app root. MainContent and ToolsPanel represent your app’s components.

import { SpatialSceneProvider } from '@metavr/layout-compat';
import { SpatialWindow } from '@metavr/layout-window-compat';

export default () => (
  <SpatialSceneProvider>
    <MainContent />
    <SpatialWindow
      label="tools"
      windowWidth={320}
      windowHeight={480}
      fallback="inline">
      <ToolsPanel />
    </SpatialWindow>
  </SpatialSceneProvider>
);

Learn the core concepts

Anchoring and layout rules: position spatial windows relative to the main window with anchors and semantic offsets.
Fallback and compatibility: keep content usable when spatial placement is not available.
Window priority: decide which windows receive limited spatial capacity first.
Best practices: design focused layouts and avoid unnecessary window reconfiguration.
Troubleshooting: diagnose startup, rendering, placement, and version problems.