WebXR in Three.js: How to Enable VR and AR

This article provides an overview of WebXR and explains how to implement immersive Virtual Reality (VR) and Augmented Reality (AR) features in a web application using the Three.js library. You will learn the core concepts of the WebXR Device API and get a step-by-step technical guide to configuring your Three.js renderer, adding initiation buttons, and setting up the render loop required for spatial computing.

What is WebXR?

WebXR is a web standard and JavaScript API that allows developers to create immersive 3D environments accessible through web browsers. The “XR” acts as an umbrella term encompassing Virtual Reality (VR), Augmented Reality (AR), and Mixed Reality (MR).

By using the WebXR Device API, web applications can directly communicate with hardware such as VR headsets (e.g., Meta Quest, HTC Vive), AR glasses, and mobile devices (iOS and Android AR capabilities). This eliminates the need for users to download native applications to experience spatial content.

Enabling WebXR in Three.js

Three.js has built-in support for WebXR, making the transition from a standard 3D webpage to an immersive experience straightforward. Follow these steps to enable VR or AR in your Three.js application.

1. Enable XR on the Renderer

To allow Three.js to handle XR sessions, you must explicitly set the xr.enabled property of your WebGLRenderer to true.

import * as THREE from 'three';

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
// Enable WebXR support
renderer.xr.enabled = true;
document.body.appendChild(renderer.domElement);

2. Add the VR or AR Activation Button

WebXR security policies require a user gesture (like a button click) to enter an immersive session. Three.js provides utility modules to generate these buttons automatically.

To enable Virtual Reality (VR):

import { VRButton } from 'three/addons/webxr/VRButton.js';

// Add the VR button to the DOM
document.body.appendChild(VRButton.createButton(renderer));

To enable Augmented Reality (AR):

import { ARButton } from 'three/addons/webxr/ARButton.js';

// Add the AR button to the DOM
document.body.appendChild(ARButton.createButton(renderer));

These buttons detect if the user’s device supports XR. If supported, the button will display “ENTER VR” or “ENTER AR”; otherwise, it will display “NOT SUPPORTED”.

3. Use the XR Animation Loop

In standard Three.js applications, the rendering loop is driven by requestAnimationFrame. However, WebXR requires the hardware device to control the frame rate. You must replace your standard loop with the renderer.setAnimationLoop method.

// Define your update and render logic
function animate() {
    // Update animations or physics here
    
    // Render the scene
    renderer.render(scene, camera);
}

// Start the WebXR-compatible loop
renderer.setAnimationLoop(animate);

4. Secure Context Requirement (HTTPS)

WebXR APIs require a secure context to function. When deploying or testing your application on external devices (like a standalone VR headset), you must serve your project over HTTPS or test locally via localhost.