Develop

Meta VR Layout SDK best practices

Updated: Oct 30, 2026

After you set up the Meta VR Layout SDK, design the core experience around the main window and treat spatial windows as focused extensions of it.

Keep the layout focused

Design for one main window and no more than two simultaneously important spatial windows. Treat capacity as platform-owned and variable.
Size windows carefully so the combined layout stays within the platform’s maximum layout area.
Keep Compose keys and React Native labels stable.
Design the declaration-site layout intentionally when using inline fallback.
Use an opaque window background. Spatial windows do not support transparency.

Set the window background color

Set the window background with WindowModifier.background(color) in Compose or the windowBackgroundColor prop in React Native. The background paints behind content, including areas exposed while the window resizes. When no color is supplied, the window uses the app theme’s android:windowBackground.

The following examples set an opaque background behind app-defined ToolsPanel content.

Jetpack Compose

import androidx.compose.ui.graphics.Color
import metavrx.layout.window.compose.layout.background

SpatialWindow(
    key = "tools",
    modifier = WindowModifier
        .size(320.dp, 480.dp)
        .background(Color(0xFF202020)),
) { ToolsPanel() }

React Native

<SpatialWindow
  label="tools"
  windowWidth={320}
  windowHeight={480}
  windowBackgroundColor="#202020">
  <ToolsPanel />
</SpatialWindow>

Keep window geometry stable

Keep window size, anchor, offset, and React Native spatial properties stable. Each geometry change crosses process boundaries to platform window management, and size changes also relayout the surface. Animate content within the window instead of changing window properties frame by frame.

The following examples keep spatial properties stable while app-owned content changes independently.

Jetpack Compose

import androidx.compose.runtime.Composable
import metavrx.layout.window.compose.SpatialWindow
import metavrx.layout.window.compose.layout.WindowAnchor
import metavrx.layout.window.compose.layout.WindowModifier
import metavrx.layout.window.compose.layout.anchor

private val toolsWindowLayout = WindowModifier.anchor(WindowAnchor.End)

@Composable
fun ToolsWindow(
    content: @Composable () -> Unit,
) {
    SpatialWindow(
        key = "tools",
        modifier = toolsWindowLayout,
        content = content,
    )
}

React Native

import type {PropsWithChildren} from 'react';
import {SpatialWindow} from '@metavr/layout-window-compat';

const toolsWindowProps = {
  label: 'tools',
  windowWidth: 320,
  windowHeight: 480,
  anchor: 'end',
} as const;

export function ToolsWindow({children}: PropsWithChildren) {
  return (
    <SpatialWindow {...toolsWindowProps}>
      {children}
    </SpatialWindow>
  );
}

Test on the Simulator and a physical device

Use Meta Spatial Simulator to test window creation, finite capacity, fallback behavior, 2D sizing and anchors, and input. The Simulator supports up to three spatial windows, but the React Native integration’s two-slot limit still applies. The Simulator approximates semantic offsets in 2D and does not reproduce every attachment or depth behavior. Always test layout changes on a physical device before shipping so you can verify depth, comfort, performance, and final appearance.