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.
ViroReact is MIT licensed and free forever.
| Platform | Support | Notes |
|---|---|---|
| iOS (ARKit) | ✅ | Deployment target 15.1 |
| Android (ARCore) | ✅ | |
| Meta Horizon OS | ✅ | Quest 2 / Pro / 3 / 3S through OpenXR; mixed reality on Quest 3 / 3S |
| Apple visionOS | ✅ | Needs the optional @reactvision/react-native-visionos peer; deployment target 26.0 |
| Web (WebGL2 / WASM) | ✅ | Needs the optional @reactvision/viro-web-renderer peer |
On Meta Quest, StudioSceneNavigator renders with HDR off, because the HDR composite hides the passthrough layer there. PBR needs HDR, so a material with the PBR lighting model, which Studio materials and glTF models use by default, is shaded as Blinn: its roughness, metalness and ambient occlusion map have no effect, and a Studio scene looks flatter than it does on a phone.
ViroReact works with both React Native CLI and Expo projects.
npm install @reactvision/react-viroFor 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
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
If you're building AR, VR or XR apps with ViroReact, our MCP server is the fastest way to get moving. Think of it as a living guide to ViroReact, always current, that plugs straight into the tools you already use.
Connect it to Claude, Codex, Cursor or any other coding agent, and your agent instantly understands how to work with ViroReact's cross-platform rendering. No hunting through docs, no guesswork. (Our documentation is still a great companion, but the MCP is the most up to date source there is.)
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)
- Co-location: two devices in the same room agreeing on where the scene is, with replicated state on top (Platform feature)
- VPS: scan a whole room to define its own persistent coordinate frame, then localise back into it later or from another device, with an optional world mesh for occlusion and physics (Platform feature)
- Advanced VPS: continuous localisation against a place's map that improves with every scan, matched on the device or on ReactVision's servers (Platform feature)
- World mesh and depth: a mesh of the real surroundings from LiDAR, ARCore depth or monocular depth, fused across frames, for occlusion and physics
Rendering
- PBR lighting, HDR environment maps, and real-time shadow casting
- 360° photo and video environments
- Portal rendering for immersive pass-through experiences
- OBJ, GLTF/GLB and VRX (FBX converted to VRX offline) model loading with embedded animations
- Custom procedural geometry and custom GPU shaders
Interaction and motion
- 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
Audio
- Spatial audio, 360° sound fields, and positioned 3D audio
Cloud Anchors, Geospatial Anchors, co-location, Advanced VPS 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, the co-location relay and geospatial infrastructure for you. Co-location and Advanced VPS server mode need a paid plan.
You can get a Studio account, which includes Platform access, for free at https://studio.reactvision.xyz.
Co-location and VPS can also run on a user token instead of rvApiKey, for an app with its own sign-in. Its backend mints a short-lived token for the signed-in user with a secret key (POST /functions/v1/app-user-tokens), and the app passes viro a function that fetches it. viro renews the token before it expires:
import { createUserTokenCredentials, useViroColocation } from "@reactvision/react-viro";
// fetchToken calls your backend and returns what app-user-tokens answered.
const credentials = useMemo(() => createUserTokenCredentials({ projectId: PROJECT_ID, fetchToken }), [userId]);
useViroColocation({ roomId, credentials }); // also useViroColocationRoom, useViroReplicatedState
<StudioSceneNavigator sceneId={sceneId} colocation={{ mode: "join", code, credentials }} />
<ViroVPS arSceneNavigator={nav} credentials={credentials} />- Cloud Anchors guide: https://viro-community.readme.io/docs/cloud-anchors
- Geospatial Anchors guide: https://viro-community.readme.io/docs/geospatial
Two capabilities are shipped as separate, opt-in packages rather than in core — install them only if you need them:
-
@reactvision/react-viro-onnx— on-device object detection. It provides the ONNX Runtime inference engine behindViroObjectDetector(model inference, NMS, class-name decoding). Without it,ViroObjectDetectorreturns no detections. Keeping it separate avoids bundling ONNX Runtime (~tens of MB) into apps that don't use detection. -
@reactvision/react-viro-face-tracking— front-camera (ARKit face-tracking) AR. It backs thefrontCameraEnabledprop onViroARSceneNavigator. On iOS ARKit reaches the front camera only through the TrueDepth API, which Apple statically scans for under App Store review Guideline 2.5.1 — so it's kept out of the core binary. Apps that don't use front-camera AR stay TrueDepth-free and pass review with no configuration; install this package (and declare TrueDepth) only when you need it. For a selfie feed without face tracking, useViroCameraTexturewithcameraPosition="front"— that's in core and uses AVFoundation, no TrueDepth.
ReactVision Studio is our browser-based visual scene editor for AR and VR. Build scenes visually in Studio, then embed them inside your own ViroReact app with a single component. Designers and developers can iterate on a scene in Studio and have it update in production without a new app build.
Build scenes visually
- Placement — drag-and-drop 3D objects, images, video, text, and primitives into a scene with visual gizmos for position, rotation, and scale. No JSX required to lay out a scene.
- AI asset generation — generate 3D models from a text prompt or reference image directly inside the editor, powered by ReactVision Platform.
- Animations — author keyframe and property animations on a timeline, chain them into sequences, and trigger them from interactions or scene events.
- Physics — assign dynamic, static, or kinematic bodies to objects, configure mass, friction, and restitution, and wire up collision callbacks — the same physics engine ViroReact ships with, exposed visually.
Embed Studio scenes in your app
Drop the StudioSceneNavigator component into your ViroReact app, point it at a Studio scene, and your app picks up whatever your team is editing in Studio without a new native build.
Getting started
Full walkthrough — including Studio setup, exporting a scene, and wiring StudioSceneNavigator into a React Native app — is in our blog: https://updates.reactvision.xyz/how-to-build-your-first-ar-vr-app-with-studio-and-react-native-f2421ecce9ae
Each scene navigator sends ReactVision one request every time it mounts, so we can see which platforms, navigators and ViroReact versions are in use. That covers ViroARSceneNavigator, Viro3DSceneNavigator, ViroVRSceneNavigator, ViroSceneNavigator, the web AR, 3D and scene navigators, and ViroXRSceneNavigator, which counts once whichever navigator it renders. The request is sent in the background after the navigator mounts. It is never retried, and a failure is ignored.
Each request carries:
- a random install id, created on first use and kept in the app's own storage (
NSUserDefaultson iOS and visionOS, a file in the no-backup directory on Android,localStorageon web), and a random id for the request itself - the app's bundle id or package name, version and build number (on web, the page's hostname)
- the platform, OS version and device model (on web, the OS family and the browser)
- the navigator, the ViroReact and React Native versions, and whether it is a development build
- whether
RVApiKeyis set (never the key itself), andRVProjectIdwhen it is set - a few of the navigator's own settings, such as the anchor provider or the occlusion mode, and never ids, keys, URLs or scene content
A web page served from localhost, 127.0.0.1, [::1], 0.0.0.0 or a .local host sends nothing. The iOS privacy manifest declares this data as Device ID, Product Interaction and Other Diagnostic Data, used for analytics, not linked to the user and not used for tracking.
To turn it off, use either of these:
- The Expo plugin option
"telemetry": false. It writesViroTelemetryEnabled=falseto Info.plist and thecom.reactvision.ViroTelemetryEnabledmeta-data with the valuefalseto AndroidManifest.xml. Without Expo, and in a visionOS app's Info.plist, set those keys yourself. ViroTelemetry.setEnabled(false)from@reactvision/react-viro, called before the first navigator mounts. It works on every platform, web included.
- 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
Guides that ship in this repository:
CHANGELOG.md— what changed, by release
Feature guides for VPS, visionOS, Quest, the web renderer, platform extensions, shaders, object detection, camera texture and session recording are on the documentation site above.
Discord is the best place to find the team and other developers building with ViroReact:
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
For independent agencies and consultants vetted by the ReactVision team: https://reactvision.xyz/partners
A huge thank you to everyone who supports ongoing development by sponsoring us on GitHub: https://github.com/sponsors/ReactVision
JetBrains supports ViroReact development through their Open Source program.
- Website: https://reactvision.xyz
- ViroReact: https://reactvision.xyz/viro-react
- ReactVision Studio: https://studio.reactvision.xyz
- Blog: https://updates.reactvision.xyz
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.
MIT licensed. © ReactVision, Inc.