What Is WebXR?

The WebXR Device API Explained

The WebXR Device API is a JavaScript interface that connects your web application to XR (extended reality) hardware through the browser. The "XR" in WebXR covers both virtual reality, where the player is fully immersed in a computer-generated environment, and augmented reality, where digital content is overlaid onto the real world. By unifying both under a single API, WebXR lets you build experiences that work across VR headsets, AR glasses, and smartphone AR modes with the same core code.

At its most basic level, WebXR does four things. First, it detects whether the user's device supports immersive sessions and what capabilities are available. Second, it manages the XR session lifecycle, handling the transition from a normal web page into an immersive experience and back again. Third, it provides spatial tracking data each frame, telling your application where the headset is in 3D space, where the controllers are, and what buttons the player is pressing. Fourth, it coordinates the render loop, calling your rendering function at the headset's native refresh rate so each frame is delivered on time.

The API operates through the navigator.xr object, which is available in any secure (HTTPS) context. You request a session by specifying the mode you want, either "immersive-vr" for full virtual reality, "immersive-ar" for augmented reality, or "inline" for a flat-screen 3D view. If the device supports the requested mode, the browser creates an XRSession that your application uses for the duration of the experience.

Each frame, your XRSession calls a callback function with an XRFrame object. This frame object contains the viewer's pose (position and orientation in 3D space), the list of active input sources (controllers, hands, or other tracked devices), and reference spaces that anchor your virtual content to either the player's physical environment or a fixed virtual coordinate system. You use this data to update your game state, position objects in the scene, and render the view from the player's perspective.

From WebVR to WebXR: What Changed

WebVR was the first attempt at bringing VR to the browser, and it shipped in experimental form in Firefox and Chrome around 2016. It worked, but it had significant limitations. WebVR only supported virtual reality, with no AR capabilities. It assumed a specific hardware model (headset with two controllers) that did not accommodate the growing diversity of XR devices. Its API design made it difficult to handle different tracking configurations, reference frames, and input methods cleanly.

The W3C Immersive Web Working Group designed WebXR as a clean replacement, not an evolution, of WebVR. Key changes include the unified XR model that supports VR, AR, and inline modes through the same session types. The reference space system was redesigned to handle everything from seated experiences to room-scale tracking to unbounded AR environments. Input handling was generalized to support controllers, hand tracking, gaze input, and any future input method through a common XRInputSource interface. Feature detection was built in from the start, letting applications query exactly which capabilities are available before requesting a session.

WebVR was officially deprecated in 2019, and no current browser supports it. All modern VR and AR browser content uses WebXR. If you encounter tutorials or code samples referencing the WebVR API (VRDisplay, getVRDisplays, requestPresent), they are outdated and should not be used for new projects.

How WebXR Fits into the Browser Stack

WebXR does not exist in isolation. It works alongside other browser APIs to deliver a complete immersive experience. Understanding these relationships helps you design better games.

WebGL and WebGPU handle the actual rendering. WebXR provides the tracking data and frame timing, but it does not draw anything. Your application renders the scene using WebGL 2 (the current standard) or WebGPU (the newer, more performant option that is still rolling out across devices). WebXR coordinates with the rendering API to ensure that each eye's view is rendered correctly and submitted to the headset's compositor at the right time.

The Gamepad API is used within WebXR to report controller button and axis states. Each XRInputSource has a gamepad property that follows the standard Gamepad API interface, giving you access to button values (pressed, touched, value) and thumbstick axes. This means your existing gamepad handling code can often be adapted for VR controllers with minimal changes.

Web Audio provides spatial audio that matches the 3D environment. When the player turns their head, sounds that were on their left should shift to match the new orientation. The Web Audio API's PannerNode supports 3D positioning, and you can tie audio source positions to objects in your WebXR scene for realistic spatial sound.

The Permissions API governs access to device sensors. Some WebXR features, particularly AR capabilities like camera access and environment sensing, require explicit user permission. The browser handles the permission prompts, and your application should be prepared for the user to deny sensor access.

Session Types and Reference Spaces

WebXR defines three session types, and choosing the right one determines what kind of experience you can build.

immersive-vr takes over the headset display completely. Your application renders both eye views, and the player sees only your virtual environment. This is the session type for fully virtual games, simulations, and experiences. It requires a VR headset or compatible device.

immersive-ar blends your rendered content with the real world. The player sees their physical environment through passthrough cameras or transparent displays, with your 3D objects appearing anchored in real space. This session type enables AR games and experiences. It requires a device with AR capabilities, such as the Meta Quest 3, Apple Vision Pro, or an ARCore-compatible Android phone.

inline renders 3D content in the regular browser page without entering an immersive mode. This is useful for previewing VR scenes on a flat screen, building "magic window" experiences on phones where tilting the device changes the view, or providing a fallback for devices without VR or AR support. Inline sessions are available on any device with a browser.

Within each session, you choose a reference space that defines how positions are measured. The "local" reference space puts the origin at the player's initial position and is suitable for seated or standing experiences in a small area. The "local-floor" space is similar but with the origin at floor level. The "bounded-floor" space includes a defined play area boundary. The "unbounded" space allows tracking across large physical areas, which is used for AR experiences where the player can walk around freely. The "viewer" space is locked to the headset itself, useful for head-locked UI elements.

WebXR Modules and Optional Features

The core WebXR specification covers session management, tracking, and basic input. Additional capabilities are provided through separate modules that devices may or may not support. Your application must check for these features before using them.

Hand input provides 25 joint positions per hand for finger tracking. Supported on the Meta Quest 3, Apple Vision Pro, and some PC VR setups with Ultraleap controllers.

Hit testing casts rays into the real world to find surface intersections. Essential for placing virtual objects on real surfaces in AR.

Plane detection identifies flat surfaces (floors, walls, tables) and reports their boundaries. Useful for physics, collision, and game area definition in AR.

Anchors pin virtual objects to specific physical locations, maintaining accurate positioning as tracking refines over time. Persistent anchors survive between sessions.

Depth sensing provides a depth map of the environment for realistic occlusion, where real objects properly hide virtual ones.

Layers allow compositing multiple rendered surfaces (like a UI panel, a video feed, and the main 3D scene) at different quality levels. Layers can improve performance by rendering UI at a lower update rate than the main scene.

Feature detection follows a consistent pattern. Before requesting a session, call navigator.xr.isSessionSupported() with your desired mode. When requesting the session, list the features you need in the requiredFeatures and optionalFeatures arrays. The browser will only create the session if all required features are supported, and it will enable optional features on a best-effort basis.