@reactvision/react-viro 2.54.0 → 2.55.0

package/README.md

@@ -1,4 +1,3 @@
-
 <p align="center" style="background-colour: #CCCCCC;">
   <a href="https://www.reactvision.xyz/">
     <img src="https://avatars.githubusercontent.com/u/74572641?s=200&v=4" alt="ReactVision logo" width="120px" height="120px">
@@ -17,78 +16,118 @@
   </a>
 </p>
 
-<h1 align="center">ViroReact (ReactVision)</h1>
+# ViroReact, By ReactVision
 
-ViroReact is a library for building Augmented Reality (AR) and Virtual Reality (VR) experiences using React Native. Viro runs your code natively across mobile VR (including Google Daydream, Samsung Gear VR, and Google Cardboard on iOS and Android) and AR platforms (iOS ARKit and Android ARCore).
+ViroReact is the most widely used open-source library for building Augmented Reality (AR) and Virtual Reality (VR) experiences with React Native. Write your app once in TypeScript and ship it natively across mobile AR and VR headsets — no new engine, no new language, no months of ramp-up.
 
-<table>
-  <tr>
-    <td align="centre">
-      <img height="200" src="https://raw.githubusercontent.com/viromedia/viro/master/code-samples/js/ARCarDemo/viro_car_marker_demo.gif" alt="AR car demo">
-    </td>
-    <td align="centre">
-      <img height="200" src="https://github.com/ViroCommunity/viro/assets/430272/b153b8e4-7b40-4197-b05b-dd1eb1566102" alt="Viro example">
-    </td>
-  </tr>
-</table>
+ViroReact is MIT licensed and free forever.
 
-## Documentation
+## Supported Platforms
+
+| Platform         | Support      |
+| ---------------- | ------------ |
+| iOS (ARKit)      | ✅ Supported |
+| Android (ARCore) | ✅ Supported |
+| Meta Horizon OS  | ✅ Supported |
+
+ViroReact works with both **React Native CLI** and **Expo** projects.
+
+## Installation
+
+```bash
+npm install @reactvision/react-viro
+```
+
+For Expo projects, the easiest way to start is to clone the official starter kit:
+
+- **Expo + TypeScript starter kit:** <https://github.com/ReactVision/expo-starter-kit-typescript>
+- **React Native CLI starter kit:** <https://github.com/ReactVision/starter-kit>
+
+For step-by-step setup instructions, including platform-specific permissions and build configuration, see the full installation guide in the docs: <https://viro-community.readme.io/docs/installation-instructions>
+
+## Features
+
+ViroReact ships with a complete spatial computing toolkit out of the box — no third-party plugins, no paid add-ons.
+
+**Tracking and anchoring**
+
+- AR plane detection with horizontal and vertical surface anchors
+- Image and object recognition triggers
+- Cloud Anchors for persistent, multi-user shared AR content _(Platform feature)_
+- Geospatial Anchors that pin content to real-world latitude, longitude, and altitude _(Platform feature)_
 
-Documentation is available here: https://viro-community.readme.io/docs/overview
+**Rendering**
 
-We do our best to keep it up to date, but you may occasionally encounter broken links or outdated samples. If you spot anything, please submit an edit or reach out on Discord: https://discord.gg/A6TaFNqwVc
+- PBR lighting, HDR environment maps, and real-time shadow casting
+- 360° photo and video environments
+- Portal rendering for immersive pass-through experiences
+- OBJ, FBX, and GLTF/GLB model loading with embedded animations
+- Custom procedural geometry and custom GPU shaders
 
-## Getting Started
+**Interaction and motion**
 
-If you’re starting a fresh project with ViroReact, clone one of the starter kits:
+- Built-in physics engine with dynamic and static bodies, collision callbacks
+- Particle system for fire, smoke, rain, snow, confetti, and other effects
+- Declarative animation system with sequencing and chaining
+- Full input event system: tap, drag, pinch, rotate, fuse, hover
 
-- Expo + TypeScript: https://github.com/ReactVision/expo-starter-kit-typescript
-- React Native: https://github.com/ReactVision/starter-kit
-- Expo + JavaScript: https://github.com/ReactVision/expo-starter-kit
+**Audio**
 
-## Examples
+- Spatial audio, 360° sound fields, and positioned 3D audio
 
-See the `./examples` directory for sample code demonstrating ViroReact usage, including automatic architecture detection and other features.
+## Platform Features
 
-You can also browse the example projects page: https://viro-community.readme.io/docs/examples  
-These are a little old (~2019), but they’re still a useful reference for many parts of the library.
+Cloud Anchors, Geospatial Anchors, and AI-powered 3D asset creation are powered by **ReactVision Platform** — managed cloud infrastructure built directly into ViroReact. Add your `rvApiKey` and `rvProjectId` and the platform handles hosting, resolution, and geospatial infrastructure for you.
 
-## Connect with the ReactVision Community
+You can get a Studio account, which includes Platform access, for free at <https://studio.reactvision.xyz>.
 
-For support, discussion, or contributing to ViroReact, Discord is the best place to find us:
+- Cloud Anchors guide: <https://viro-community.readme.io/docs/cloud-anchors>
+- Geospatial Anchors guide: <https://viro-community.readme.io/docs/geospatial-anchors>
+
+## Documentation
+
+- Full API reference and guides: <https://viro-community.readme.io/docs/overview>
+- Getting started tutorial: <https://updates.reactvision.xyz/get-started-with-the-viroreact-and-expo-starter-kit-a9ca88803e5a>
+
+## Community
+
+Discord is the best place to find the team and other developers building with ViroReact:
 
 <a href="https://discord.gg/A6TaFNqwVc">
-  <img src="https://discordapp.com/api/guilds/774471080713781259/widget.png?style=banner2" alt="Discord Banner"/>
+  <img src="https://discordapp.com/api/guilds/774471080713781259/widget.png?style=banner2" />
 </a>
 
-## External Support
+## Enterprise Support and Partners
 
-If you need hands-on help, we maintain a list of trusted partners you can hire:  
-https://viro-community.readme.io/docs/hire-a-viro-react-expert
+For teams adopting XR at scale, the ReactVision team works directly with you on architecture, migrations from 8th Wall or Unity, performance audits, and shipping production experiences. <https://reactvision.xyz/contact>
 
-All partners are vetted by the ReactVision team and have experience shipping production-grade apps with Viro.
+For independent agencies and consultants vetted by the ReactVision team: <https://reactvision.xyz/partners>
 
-## Powered by
+## Supporters
 
-[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSource)
+A huge thank you to everyone who supports ongoing development by sponsoring us on GitHub: <https://github.com/sponsors/ReactVision>
 
-## Supporters
+- [Device Cloud](https://devicecloud.dev/)
+- [Looking Glass](http://looking-glass.space)
+- [@lentesta](https://github.com/lentesta)
+
+## Powered by
 
-A huge thank you to everyone who supports ongoing development by sponsoring us on GitHub:  
-https://github.com/sponsors/ReactVision
+[![JetBrains logo](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSource)
 
-- https://github.com/devicecloud-dev — Device Cloud: https://devicecloud.dev/
-- https://github.com/lentesta
-- Looking Glass: http://looking-glass.space
+JetBrains supports ViroReact development through their [Open Source program](https://jb.gg/OpenSource).
 
-## A little history…
+## Find Out More
 
-ViroReact was originally developed by Viro Media (http://www.viromedia.com/) and open-sourced in 2019.
+- Website: <https://reactvision.xyz>
+- ViroReact: <https://reactvision.xyz/viro-react>
+- ReactVision Studio: <https://studio.reactvision.xyz>
+- Blog: <https://updates.reactvision.xyz>
 
-In late 2020, the Viro Community formed to help maintain and modernise the project—keeping it compatible with current React Native versions and expanding functionality over time.
+## A little history…
 
-In 2025, Morrow acquired ReactVision (https://www.themorrow.digital/blog/morrow-acquires-reactvision-and-viroreact-library) to accelerate development and invest in the future of ViroReact. ReactVision now has a full-time team working to keep the codebase current and ready for the next generation of XR / spatial computing.
+ViroReact was originally developed by Viro Media and open-sourced in 2019. In late 2020, the Viro Community formed to maintain and modernise the project, keeping it compatible with current React Native versions. In January 2025, Morrow Digital acquired the project to invest in its future, and in late 2025 ReactVision was spun out as an independent company with a full-time team building the next generation of XR tooling.
 
-Our vision is to enable React Native developers to build AR and VR applications that run across XR devices (smartphones, smart glasses, and headsets) from a single React Native codebase.
+---
 
-We (as a community) owe a great debt to Viro Media and the original authors of this library, and we hope to make them proud as it continues to grow within ReactVision.
+MIT licensed. © ReactVision, Inc.

package/components/AR/ViroARCamera.tsx

@@ -14,11 +14,16 @@
 import * as React from "react";
 import { ViewProps } from "react-native";
 import { ViroCamera } from "../ViroCamera";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 export class ViroARCamera extends React.Component<ViewProps> {
   _component: ViroCamera | null = null;
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARCamera is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this to check props
     return (
       <ViroCamera

package/components/AR/ViroARImageMarker.tsx

@@ -19,6 +19,7 @@ import {
   ViroARAnchorUpdatedEvent,
 } from "../Types/ViroEvents";
 import { ViroBase } from "../ViroBase";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 /**
  * Container for Viro Components anchored to a detected image.
@@ -47,6 +48,10 @@ export class ViroARImageMarker extends ViroBase<{}> {
   };
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARImageMarker is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARImageMarker", this.props);
 

package/components/AR/ViroARObjectMarker.tsx

@@ -14,6 +14,7 @@
 import { ViroBase } from "../ViroBase";
 import * as React from "react";
 import { NativeSyntheticEvent, requireNativeComponent } from "react-native";
+import { isQuest } from "../Utilities/ViroPlatform";
 import {
   ViroARAnchorFoundEvent,
   ViroARAnchorRemovedEvent,
@@ -45,6 +46,10 @@ export class ViroARObjectMarker extends ViroBase<Props> {
   }
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARObjectMarker is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARObjectMarker", this.props);
 

package/components/AR/ViroARPlane.tsx

@@ -19,6 +19,7 @@ import {
 import { ViroBase } from "../ViroBase";
 import * as React from "react";
 import { NativeSyntheticEvent, requireNativeComponent } from "react-native";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 type Props = {
   anchorId?: string;
@@ -58,6 +59,10 @@ export class ViroARPlane extends ViroBase<Props> {
   };
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARPlane is not supported on Quest and will not render.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARPlane", this.props);
 

package/components/AR/ViroARPlaneSelector.tsx

@@ -13,6 +13,7 @@
 
 import { ViroAnchor, ViroPlaneUpdatedMap } from "../Types/ViroEvents";
 import * as React from "react";
+import { isQuest } from "../Utilities/ViroPlatform";
 import { ViroMaterials } from "../Material/ViroMaterials";
 import { ViroNode } from "../ViroNode";
 import { ViroQuad } from "../ViroQuad";
@@ -416,6 +417,10 @@ export class ViroARPlaneSelector extends React.Component<Props, State> {
   // ---------------------------------------------------------------------------
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARPlaneSelector is not supported on Quest and will not render.");
+      return null;
+    }
     return <ViroNode>{this._renderPlanes()}</ViroNode>;
   }
 

package/components/AR/ViroARScene.tsx

@@ -50,6 +50,7 @@ import { ViroCamera } from "../ViroCamera";
 import { ViroTrackingStateConstants } from "../ViroConstants";
 import { ViroCommonProps } from "./ViroCommonProps";
 import { ViroOrbitCamera } from "components/ViroOrbitCamera";
+import { isQuest } from "../Utilities/ViroPlatform";
 
 const ViroCameraModule = NativeModules.ViroCameraModule;
 
@@ -413,6 +414,10 @@ export class ViroARScene extends ViroBase<Props> {
   };
 
   render() {
+    if (isQuest) {
+      console.warn("[Viro] ViroARScene is not supported on Quest and will not render. Use ViroScene instead.");
+      return null;
+    }
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARScene", this.props);
 

package/components/AR/ViroARSceneNavigator.tsx

@@ -18,8 +18,11 @@ import {
   NativeModules,
   requireNativeComponent,
   StyleSheet,
+  Text,
+  View,
   ViewProps,
 } from "react-native";
+import { isQuest } from "../Utilities/ViroPlatform";
 import {
   ViroWorldOrigin,
   ViroProvider,
@@ -75,6 +78,13 @@ type Props = ViewProps & {
   };
   initialSceneKey?: string;
 
+  /**
+   * Optional fallback rendered when this navigator is mounted on a Meta Quest
+   * device (where AR is not supported). When omitted, a default message view
+   * is rendered. Pass `null` to render nothing.
+   */
+  questFallback?: React.ReactNode;
+
   autofocus?: boolean;
   /**
    * iOS only props! Note: these props may change as the underlying platforms coalesce in features.
@@ -232,6 +242,7 @@ type State = {
  * ViroARSceneNavigator is used to transition between multiple AR Scenes.
  */
 export class ViroARSceneNavigator extends React.Component<Props, State> {
+  static _questWarningLogged = false;
   _component: ViroNativeRef = null;
 
   constructor(props: Props) {
@@ -1127,6 +1138,16 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     );
   };
 
+  _rvGetProject = async (): Promise<any> => {
+    return await ViroARSceneNavigatorModule.rvGetProject(findNodeHandle(this));
+  };
+
+  _rvGetScene = async (sceneId: string): Promise<any> => {
+    return await ViroARSceneNavigatorModule.rvGetScene(
+      findNodeHandle(this), sceneId
+    );
+  };
+
   _rvGetSceneAssets = async (sceneId: string): Promise<any> => {
     return await ViroARSceneNavigatorModule.rvGetSceneAssets(
       findNodeHandle(this), sceneId
@@ -1422,6 +1443,8 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     rvAttachAssetToCloudAnchor: this._rvAttachAssetToCloudAnchor,
     rvRemoveAssetFromCloudAnchor: this._rvRemoveAssetFromCloudAnchor,
     rvTrackCloudAnchorResolution: this._rvTrackCloudAnchorResolution,
+    rvGetProject: this._rvGetProject,
+    rvGetScene: this._rvGetScene,
     rvGetSceneAssets: this._rvGetSceneAssets,
     // Assets API
     rvUploadAsset: this._rvUploadAsset,
@@ -1481,6 +1504,8 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     rvAttachAssetToCloudAnchor: this._rvAttachAssetToCloudAnchor,
     rvRemoveAssetFromCloudAnchor: this._rvRemoveAssetFromCloudAnchor,
     rvTrackCloudAnchorResolution: this._rvTrackCloudAnchorResolution,
+    rvGetProject: this._rvGetProject,
+    rvGetScene: this._rvGetScene,
     rvGetSceneAssets: this._rvGetSceneAssets,
     // Assets API
     rvUploadAsset: this._rvUploadAsset,
@@ -1502,6 +1527,26 @@ export class ViroARSceneNavigator extends React.Component<Props, State> {
     // Uncomment this line to check for misnamed props
     //checkMisnamedProps("ViroARSceneNavigator", this.props);
 
+    if (isQuest) {
+      if (!ViroARSceneNavigator._questWarningLogged) {
+        console.warn(
+          "[Viro] ViroARSceneNavigator is not supported on Meta Quest. " +
+            "Use ViroXRSceneNavigator (auto-detects Quest) or ViroVRSceneNavigator instead."
+        );
+        ViroARSceneNavigator._questWarningLogged = true;
+      }
+      if ("questFallback" in this.props) {
+        return <>{this.props.questFallback}</>;
+      }
+      return (
+        <View style={[styles.container, styles.questFallback]}>
+          <Text style={styles.questFallbackText}>
+            AR is not supported on Meta Quest.
+          </Text>
+        </View>
+      );
+    }
+
     const items = this._renderSceneStackItems();
 
     // update the arSceneNavigator with the latest given props on every render
@@ -1550,6 +1595,15 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     alignItems: "center",
   },
+  questFallback: {
+    backgroundColor: "#000",
+    padding: 24,
+  },
+  questFallbackText: {
+    color: "#fff",
+    fontSize: 16,
+    textAlign: "center",
+  },
 });
 
 const VRTARSceneNavigator = requireNativeComponent<any>(