Getting Started with WebXR and Three.js

WebXR is the web standard that enables AR and VR experiences in browsers. No app store, no installation, no developer account required — users click a link and enter an immersive experience. For reaching broad audiences with AR campaigns, for prototyping XR interactions, and for building XR tools that need to run anywhere, WebXR is the most accessible XR platform available.

Three.js is the dominant JavaScript library for 3D graphics on the web, and the most popular foundation for WebXR experiences. This guide walks you through the WebXR ecosystem, Three.js fundamentals, and building your first interactive AR/VR web experience.


Understanding the WebXR Ecosystem

The WebXR Device API

WebXR Device API is the W3C standard that lets JavaScript code access immersive AR and VR capabilities. It handles requesting XR sessions ('immersive-vr' or 'immersive-ar'), managing the render loop at headset refresh rates, accessing 6DoF pose data, handling controller and hand tracking input, and AR features like hit testing and plane detection.

Three.js WebXR Support

Three.js includes first-class WebXR support through its WebXRManager class. Setting renderer.xr.enabled = true is all that is needed to enable WebXR mode. Three.js handles the WebXR render loop, camera management, and controller/hand integration automatically.

Alternative Frameworks

A-Frame (aframe.io) is an HTML-based declarative XR framework built on Three.js. Writing XR scenes in HTML rather than JavaScript makes it approachable for web developers without 3D backgrounds. Babylon.js is a full 3D engine with strong enterprise tooling, TypeScript support, and an inspector debugger. React Three Fiber brings Three.js into the React component model, useful for web apps integrating XR into larger React codebases.

Setting Up Your First Three.js WebXR Project

The minimal WebXR setup with Three.js requires a scene, camera, renderer, and the VR button component. Here is the essential project structure:

- Install Three.js via npm: npm install three - Create a basic scene: new THREE.Scene() - Add a PerspectiveCamera positioned at eye height (1.6m) - Create a WebGLRenderer with { antialias: true } - Enable XR: renderer.xr.enabled = true - Add the VR button: document.body.appendChild(VRButton.createButton(renderer)) - Start an XR-compatible render loop: renderer.setAnimationLoop(render) Add a simple test scene: a BoxGeometry with MeshStandardMaterial, a PointLight, and an AmbientLight. Deploy to a web server (HTTPS is required for WebXR — localhost works for development). Open in Chrome on Meta Quest browser, click the "Enter VR" button, and you are in your first WebXR scene.

Building Interactions in WebXR with Three.js

Controller Input

Three.js WebXR provides XRController objects accessible via renderer.xr.getController(index). Controllers dispatch selectstart, selectend, and connected events. Map controller buttons to game actions using the WebXR Gamepad API. The XRControllerModelFactory renders realistic controller 3D models automatically.

Hand Tracking

Hand tracking uses XRHand objects with joint poses for all 25 joints in each hand. The XRHandModelFactory renders hand meshes. Gesture detection is built on top of joint pose data — a pinch gesture is detected by measuring the distance between the index tip and thumb tip joints. Libraries like handy-work abstract common gestures.

Hit Testing for AR

WebXR hit testing detects real-world surfaces for placing virtual content in AR sessions. Request 'hit-test' feature in the XR session options, create an XRHitTestSource, then test each frame to get hit test results. Place objects at the hit test intersection point when the user taps or selects.

Deploying WebXR Experiences

WebXR requires HTTPS. For development, localhost works. For production deployment: Netlify and Vercel both provide free HTTPS hosting with simple git-based deployment. GitHub Pages works for static Three.js projects. Ensure your web server sends the correct MIME types for .gltf and .glb files (model/gltf+json and model/gltf-binary).

The biggest advantage of WebXR is frictionless distribution. Share a URL, and anyone with a compatible browser and device can experience your creation. This makes WebXR ideal for consumer-facing AR campaigns, conference demos, and prototyping — anywhere you need broad reach without the friction of app store distribution.