Develop

Window priority

Updated: Aug 27, 2026
After you set up the Meta VR Layout SDK, use priority to express which windows matter most when demand exceeds the capacity available from Horizon OS.

Assign priorities

Higher integer priorities receive spatial capacity before lower priorities. The default priority is 0. Windows with equal priorities retain their first-registration order. If your app might show more than two spatial windows, define semantic tiers such as PermanentFixture, Popup, and Ephemeral, then assign each window to a tier based on its role.
The following examples define three app-owned tiers. If only two spatial slots are available, the ephemeral window has the lowest priority and is not shown.
import metavrx.layout.window.compose.SpatialWindow

// App-defined priority tiers.
object AppWindowPriority {
    const val PermanentFixture = 3
    const val Popup = 2
    const val Ephemeral = 1
}

SpatialWindow(
    key = "navigation",
    priority = AppWindowPriority.PermanentFixture,
) { NavigationPanel() }

SpatialWindow(
    key = "popup",
    priority = AppWindowPriority.Popup,
) { PopupPanel() }

// Lowest tier: not shown when only two spatial slots are available.
SpatialWindow(
    key = "tip",
    priority = AppWindowPriority.Ephemeral,
) { TipPanel() }

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

// App-defined priority tiers.
const AppWindowPriority = {
  PermanentFixture: 3,
  Popup: 2,
  Ephemeral: 1,
} as const;

<>
  <SpatialWindow
    label="navigation"
    windowWidth={320}
    windowHeight={480}
    priority={AppWindowPriority.PermanentFixture}>
    <NavigationPanel />
  </SpatialWindow>

  <SpatialWindow
    label="popup"
    windowWidth={320}
    windowHeight={240}
    priority={AppWindowPriority.Popup}>
    <PopupPanel />
  </SpatialWindow>

  {/* Lowest tier: not shown when only two spatial slots are available. */}
  <SpatialWindow
    label="tip"
    windowWidth={240}
    windowHeight={160}
    priority={AppWindowPriority.Ephemeral}
    fallback="drop">
    <TipPanel />
  </SpatialWindow>
</>

Handle displacement

When all slots are full, a new window can replace an active window with lower priority. The displaced window uses its fallback strategy. It can return when a slot becomes available.
Compose learns available capacity from the platform. The current React Native integration reserves two spatial window slots.
Nav Logo
English (US)
© 2026 Meta