StudioSceneNavigator

Introduced in ViroReact 2.55.0

StudioSceneNavigator is the runtime bridge between ReactVision Studio and the ViroReact renderer. It is a drop-in component that fetches a scene authored in ReactVision Studio, resolves all of its assets, animations, materials, and scene functions, and renders it cross-reality — AR on iOS and Android phones, VR on Meta Quest — using ViroXRSceneNavigator underneath.

In other words: StudioSceneNavigator is to Studio-authored scenes what ViroARSceneNavigator is to hand-coded AR scenes. Most apps built with Studio mount one StudioSceneNavigator and let it handle the rest.

Studio integration

StudioSceneNavigator requires a Studio account and a configured rvApiKey / rvProjectId in your Expo plugin config. For step-by-step setup — generating credentials, configuring the plugin, and creating a project — see the ReactVision Studio Setup guide.

The component talks to the Studio backend through VRTStudioModule.rvGetProject() and VRTStudioModule.rvGetScene(sceneId) internally — no API keys or endpoint URLs are present in your JS bundle.

Platform compatibility

Platform	Supported	Notes
iOS	✅	Renders the Studio scene in AR (ARKit) via `ViroXRSceneNavigator`'s AR path
Android	✅	Renders the Studio scene in AR (ARCore) via `ViroXRSceneNavigator`'s AR path
Meta Quest	✅	Renders the Studio scene in VR via `VRActivity`. `StudioARScene` swaps its root to `ViroScene` automatically on Quest
Apple visionOS	❌	Not currently supported

Required Expo / React Native versions

StudioSceneNavigator is built on top of ViroXRSceneNavigator and inherits the same runtime gates.

Path	Minimum Expo SDK	Minimum React Native
AR (iOS / non-Quest Android)	54	0.81
VR (Meta Quest)	55	0.83

If you only need AR, you can stay on Expo 54. If your app uses VR on Quest, upgrade to Expo 55 / RN 0.83. See the Meta Quest setup guide for full configuration steps.

Very basic example

In the simplest case you can mount StudioSceneNavigator with no props at all:

import * as React from "react";
import { StudioSceneNavigator } from "@reactvision/react-viro";

export default function App() {
  return <StudioSceneNavigator />;
}

With no sceneId provided, the navigator resolves a scene to load automatically from the Studio project configured in your app's manifest (RVProjectId, set when you configure the Expo plugin — see the ReactVision Studio Setup guide). It picks a scene in the following order:

The project's opening scene, if one has been set. You can configure this in Studio via Edit Project, where you can mark any scene in the project as the opening scene.
If no opening scene has been set, the first scene in the project's scene list.

This is the recommended pattern for most apps: configure your project once in Studio, set an opening scene, and let StudioSceneNavigator do the rest. You can change which scene loads first by editing the project in Studio — no app code or rebuild required.

Basic example

For more control, you can load a specific scene by its Studio UUID and wire up lifecycle callbacks:

import * as React from "react";
import { StyleSheet } from "react-native";
import { StudioSceneNavigator } from "@reactvision/react-viro";

export default function App() {
  return (
    <StudioSceneNavigator
      sceneId="abc-123-uuid"
      onSceneReady={() => console.log("scene ready")}
      onError={(err) => console.error(err)}
      style={StyleSheet.absoluteFill}
    />
  );
}

Opening-scene resolution order with sceneId provided:

sceneId prop.
(sceneId not provided) → the project's opening scene (set in Studio via Edit Project).
(No opening scene set) → the first scene in the project's scene list.

The same component runs unmodified on Quest. On Quest, StudioSceneNavigator waits for the scene data to resolve before mounting ViroXRSceneNavigator — that way VRActivity launches directly into the content scene rather than a placeholder, and a loading spinner is shown in the panel until the scene is ready. As with ViroXRSceneNavigator, always wire onExitViro so the panel can navigate away after VR ends:

<StudioSceneNavigator
  sceneId="abc-123-uuid"
  onExitViro={() => navigation.goBack()}
/>

Props

Prop	Type	Default	Description
`sceneId`	`string`	—	UUID of a specific Studio scene to load. If omitted, the navigator fetches the project from the app manifest and uses its opening scene.
`worldAlignment`	`"Gravity" \| "GravityAndHeading" \| "Camera"`	`"Gravity"`	Forwarded to the underlying `ViroXRSceneNavigator` AR path.
`autofocus`	`boolean`	`true`	Forwarded to the underlying `ViroXRSceneNavigator` AR path.
`style`	`ViewStyle`	`StyleSheet.absoluteFill`	Forwarded to the underlying `ViroXRSceneNavigator`.
`onSceneReady`	`() => void`	—	Fires once the Studio scene has been fetched, parsed, and mounted.
`onError`	`(err: Error) => void`	—	Fires if the scene fetch, parse, or mount fails. If omitted, errors are logged with `console.error`.
`onSceneChange`	`(sceneId: string, sceneName: string) => void`	—	Fires when navigation between Studio scenes occurs (for example via a Studio-authored `NAVIGATION` scene function).
`onExitViro`	`() => void`	—	Forwarded to `ViroXRSceneNavigator`. Fires when `exitVRScene()` is called. Use this to navigate away from the screen after VR ends, otherwise it'll be blank.

Methods

StudioSceneNavigator does not currently expose navigator methods directly on its ref. Scene-to-scene navigation in Studio-authored content is driven by the Studio scene-function model (NAVIGATION actions wired up in the editor), not imperatively from app code.

If you need imperative push/pop control over the underlying scene stack, use ViroXRSceneNavigator directly and mount Studio content yourself via StudioARScene.