What are WebXR Device APIs?

WebXR is a group of standards being implemented by the browsers, which are used together to support rendering 3D scenes to hardware designed for Mixed Reality. Mixed Reality devices are presenting virtual worlds (virtual reality, or VR), or for adding graphical imagery to the real world, (augmented reality, or AR).

The WebXR Device API implements the core of the WebXR feature set, managing the selection of output devices, render the 3D scene to the chosen device at the appropriate frame rate, and manage input, such as controllers and hand interactions.

WebXR Device APIs are replacing the deprecated WebVR API. WebVR API was designed with only VR devices in mind. With the addition of new AR headsets and AR capable handheld devices, the WebVR API is deprecated in favor of WebXR Device APIs, that include AR Modules.

Introduction
WebXR Device APIs:
Immersive Devices
VR Headsets for Mobile Devices.
Oculus Quest
Augmented Reality(AR) or Mixed Reality(MR) Headsets
WebXR with Mobile Devices
Pokemon Go
WebVR vs WebXR
Virtual Reality on the Web
Mozilla Hello WebXR Demo:
WebXR Features 11: 30 Gamepad API
Input Profiles Library
WebAR Module
Hit Test
How to Get Started Building WebXR Experiences
WebGL
WebXR Libraries
ThreeJS:
A-Frame:
BabylonJS:
React 360:
PlayCanvas:
More on A-Frame
A-Frame Hello World Code
Future of WebXR APIs
WebXR Accessibility and DOM Overlay API
Lighting Estimation Using Computer Vision
Anchors
Layers
Hand Interactions
WebXR Resources 30: 10 How to Get Involved with Immersive Web Working and Community Groups

Which Devices are Compatible with WebXR?

WebXR-compatible devices include fully-immersive 3D headsets(VR Headsets) with motion and orientation tracking, Augmented Reality glasses, like HoloLens and MagicLeap ,which overlay graphics atop the real world scene passing through the frames, and AR compatible(ARCore and ARKit supported) handheld mobile phones which augment reality by capturing the world with a camera and augment that scene with computer-generated imagery.

iOS devices such as iPhone and iPad currently does not support WebXR APIs in Safari or Chrome but WebXR Viewer App is available from the App Store:

Which Browsers support WebXR?

Different browsers are implementing and WebXR APIs in different timeframes. Currently Chrome and new Edge browsers have WebXR APIs turned on as default and some of the features are under experimental flags.

You can check the current support status at CanIUse.com.

How to try out experimental features in Chrome and Edge

You can turn on experimental flags by navigating to chrome://flags/ or edge://flags/ and searching for the experimental flag you are looking to enable and choosing enable from the drop down menu.

What is the Lifecycle of a WebXR Application?

The basic steps most WebXR applications will go through are:

Query to see if the desired XR mode is supported.
If support is available, advertise XR functionality to the user.

What is XRReferenceSpaceType?

XRReferenceSpaceType defines how much your user can move in you experience.

XRReferenceSpaceType

Description

Interface

bounded-floor

Similar to the local type, except the user is not expected to move outside a predetermined boundary, given by the in the returned object.

local

A tracking space whose native origin is located near the viewer's position at the time the session was created. The exact position depends on the underlying platform and implementation. The user isn't expected to move much if at all beyond their starting position, and tracking is optimized for this use case.

For devices with six degrees of freedom (6DoF) tracking, the local reference space tries to keep the origin stable relative to the environment.

Project

Create your first AR & VR applications on the Web

In this section, we will turn our 3D experience from the last section into an immersive experience. We will develop on our local device, laptop or desktop and run the code locally.

Prerequisites

You can follow along the tutorial using an online editor. If you want to learn how to develop on your local environment, please follow the below checklist.

Download the tools listed in .
Optional: Create a Github account if you don't already have one.
Optional: install git on your development device.
Enable developer mode on your mobile device(, , ) and/or AR/VR headset. (, , ).
Have a usb cable ready to connect your mobile device or headset to your development device.

How to enable VR?

There are few changes we need to make to turn our experience into a VR experience.

Import VR button into your scene.

Enable XR on renderer.

How to enable AR and Hit-test?

Similar to VR experience, you can add AR Button to enable AR experiences. Additionally, you can specify the required and optional AR features your experience will use.

import { ARButton } from "/jsm/webxr/ARButton";

document.body.appendChild(ARButton.createButton(renderer, { requiredFeatures: ["hit-test"] }));

Add a controller: Returns a Group representing the so called target ray space of the controller. Use this space for visualizing 3D objects that support the user in pointing tasks like UI interaction.

	controller = renderer.xr.getController(0);
	controller.addEventListener("select", onSelect);
	scene.add(controller);

When we are hitting a surface, to indicate the surface, we will create a reticle to our scene.

	//Hit-test indicator
	reticle = new Mesh(new RingBufferGeometry(0.15, 0.2, 32).rotateX(-Math.PI / 2), new MeshBasicMaterial());
	reticle.matrixAutoUpdate = false;
	reticle.visible = false;
	scene.add(reticle);

Let's define the onSelect event that we attached to controller. When the select event happen, meaning user decides to place the object and we create it on the chosen location.

Finally in our render function, we will check in every XRFrame if we have an hit-test source to display the reticle on the surface.

To run the code on your device, you have to give access to your camera when prompted.

How to debug and test your WebXR Application with Chrome Dev Tools?

Enable Developer mode on your device
Navigate to edge://inspect/#devices on Edge or chrome://inspect/#devices on Chrome browser.
Click on port forwarding

How to load a 3D Model

Only a few loaders (e.g. ObjectLoader) are included by default with three.js — others should be added to your app individually.

Once you've imported a loader, you're ready to add a model to your scene. Syntax varies among different loaders — when using another format, check the examples and documentation for that loader. For glTF, usage with global scripts would be:

Change the onSelect function to load and place the model, instead of the Sphere mesh we were placing previously.

We can add event callbacks for loading manager.

See GLTFLoader documentation for further details.

Exercise

Try other object types and loaders to add different models to your scene. You can find more models under three.js/examples/models.

Troubleshooting

You've spent hours modeling an artisanal masterpiece, you load it into the webpage, and — oh no! 😭 It's distorted, miscolored, or missing entirely. Start with these troubleshooting steps:

Check the JavaScript console for errors, and make sure you've used an onError callback when calling .load() to log the result.
View the model in another application. For glTF, drag-and-drop viewers are available for and . If the model appears correctly in one or more applications, . If the model cannot be shown in any application, we strongly encourage filing a bug with the application used to create the model.

What could go wrong?

If you are running into issues, check out the scenarios below that might be causing the problem.

Serving your site using http

You would not be able to see your site if you are serving over http. WebXR APIs require secure htttps server.

Which Browsers support WebXR?

You can check the current support status at CanIUse.com.

How to try out experimental features in Chrome and Edge

What is XRReferenceSpaceType?

XRReferenceSpaceType defines how much your user can move in you experience.

XRReferenceSpaceType

Description

Interface

bounded-floor

Similar to the local type, except the user is not expected to move outside a predetermined boundary, given by the in the returned object.

local

For devices with six degrees of freedom (6DoF) tracking, the local reference space tries to keep the origin stable relative to the environment.

What is the Lifecycle of a WebXR Application?

The basic steps most WebXR applications will go through are:

Query to see if the desired XR mode is supported.
If support is available, advertise XR functionality to the user.

Similar to the local type, except the starting position is placed in a safe location for the viewer to stand, where the value of the y axis is 0 at floor level. If that floor level isn't known, the user agent will estimate the floor level. If the estimated floor level is non-zero, the browser is expected to round it such a way as to avoid fingerprinting (likely to the nearest centimeter).

A tracking space which allows the user total freedom of movement, possibly over extremely long distances from their origin point. The viewer isn't tracked at all; tracking is optimized for stability around the user's current position, so the native origin may drift as needed to accommodate that need.

A tracking space whose native origin tracks the viewer's position and orientation. This is used for environments in which the user can physically move around, and is supported by all instances of XRSession, both immersive and inline, though it's most useful for inline sessions. It's particularly useful when determining the distance between the viewer and an input, or when working with offset spaces. Otherwise, typically, one of the other reference space types will be used more often.

How to debug and test your WebXR Application with Chrome Dev Tools?

Enable Developer mode on your device
Navigate to edge://inspect/#devices on Edge or chrome://inspect/#devices on Chrome browser.
Click on port forwarding

How to enable VR?

There are few changes we need to make to turn our experience into a VR experience.

Import VR button into your scene.

Enable XR on renderer.

Which Devices are Compatible with WebXR?

iOS devices such as iPhone and iPad currently does not support WebXR APIs in Safari or Chrome but WebXR Viewer App is available from the App Store:

renderer.setAnimationLoop(animate);

import { VRButton } from "/jsm/webxr/VRButton";

renderer.xr.enabled = true;
document.body.appendChild(VRButton.createButton(renderer));

renderer.xr.enabled = true;
document.body.appendChild(VRButton.createButton(renderer));

How to load a 3D Model

Only a few loaders (e.g. ObjectLoader) are included by default with three.js — others should be added to your app individually.

import { GLTFLoader } from '/jsm/loaders/GLTFLoader.js';

//Model loader
const manager = new LoadingManager();
const loader = new GLTFLoader(manager).setPath("/assets/models/AyaSofia/");
let modelLoaded = false;

Change the onSelect function to load and place the model, instead of the Sphere mesh we were placing previously.

function onSelect() {
	if (reticle.visible && !modelLoaded) {
		loader.load(
			"GM_poly.gltf",
			function (gltf) {
				gltf.scene.children[0].position.setFromMatrixPosition(reticle.matrix);
				scene.add(gltf.scene);
				modelLoaded = true;
			},
			undefined,
			function (error) {
				console.error(error);
			}
		);
	}
}

We can add event callbacks for loading manager.

manager.onStart = function (url, itemsLoaded, itemsTotal) {
	console.log("Started loading file: " + url + ".\nLoaded " + itemsLoaded + " of " + itemsTotal + " files.");
};

manager.onLoad = function () {
	console.log("Loading complete!");
};

manager.onProgress = function (url, itemsLoaded, itemsTotal) {
	console.log("Loading file: " + url + ".\nLoaded " + itemsLoaded + " of " + itemsTotal + " files.");
};

manager.onError = function (url) {
	console.log("There was an error loading " + url);
};

See GLTFLoader documentation for further details.

Exercise

Try other object types and loaders to add different models to your scene. You can find more models under three.js/examples/models.

Troubleshooting

You've spent hours modeling an artisanal masterpiece, you load it into the webpage, and — oh no! 😭 It's distorted, miscolored, or missing entirely. Start with these troubleshooting steps:

Check the JavaScript console for errors, and make sure you've used an onError callback when calling .load() to log the result.
View the model in another application. For glTF, drag-and-drop viewers are available for and . If the model appears correctly in one or more applications, . If the model cannot be shown in any application, we strongly encourage filing a bug with the application used to create the model.

import { GLTFLoader } from '/jsm/loaders/GLTFLoader.js';

//Model loader
const manager = new LoadingManager();
const loader = new GLTFLoader(manager).setPath("/assets/models/AyaSofia/");
let modelLoaded = false;

function onSelect() {
	if (reticle.visible && !modelLoaded) {
		loader.load(
			"GM_poly.gltf",
			function (gltf) {
				gltf.scene.children[0].position.setFromMatrixPosition(reticle.matrix);
				scene.add(gltf.scene);
				modelLoaded = true;
			},
			undefined,
			function (error) {
				console.error(error);
			}
		);
	}
}

manager.onStart = function (url, itemsLoaded, itemsTotal) {
	console.log("Started loading file: " + url + ".\nLoaded " + itemsLoaded + " of " + itemsTotal + " files.");
};

manager.onLoad = function () {
	console.log("Loading complete!");
};

manager.onProgress = function (url, itemsLoaded, itemsTotal) {
	console.log("Loading file: " + url + ".\nLoaded " + itemsLoaded + " of " + itemsTotal + " files.");
};

manager.onError = function (url) {
	console.log("There was an error loading " + url);
};

What are WebXR Device APIs?

Introduction
WebXR Device APIs:
Immersive Devices
VR Headsets for Mobile Devices.
Oculus Quest
Augmented Reality(AR) or Mixed Reality(MR) Headsets
WebXR with Mobile Devices
Pokemon Go
WebVR vs WebXR
Virtual Reality on the Web
Mozilla Hello WebXR Demo:
WebXR Features 11: 30 Gamepad API
Input Profiles Library
WebAR Module
Hit Test
How to Get Started Building WebXR Experiences
WebGL
WebXR Libraries
ThreeJS:
A-Frame:
BabylonJS:
React 360:
PlayCanvas:
More on A-Frame
A-Frame Hello World Code
Future of WebXR APIs
WebXR Accessibility and DOM Overlay API
Lighting Estimation Using Computer Vision
Anchors
Layers
Hand Interactions
WebXR Resources 30: 10 How to Get Involved with Immersive Web Working and Community Groups

What could go wrong?

If you are running into issues, check out the scenarios below that might be causing the problem.

Serving your site using http

You would not be able to see your site if you are serving over http. WebXR APIs require secure htttps server.

Project

Create your first AR & VR applications on the Web

In this section, we will turn our 3D experience from the last section into an immersive experience. We will develop on our local device, laptop or desktop and run the code locally.

Prerequisites

You can follow along the tutorial using an online editor. If you want to learn how to develop on your local environment, please follow the below checklist.

Download the tools listed in .
Optional: Create a Github account if you don't already have one.
Optional: install git on your development device.
Enable developer mode on your mobile device(, , ) and/or AR/VR headset. (, , ).
Have a usb cable ready to connect your mobile device or headset to your development device.

How to enable AR and Hit-test?

Similar to VR experience, you can add AR Button to enable AR experiences. Additionally, you can specify the required and optional AR features your experience will use.

import { ARButton } from "/jsm/webxr/ARButton";

document.body.appendChild(ARButton.createButton(renderer, { requiredFeatures: ["hit-test"] }));

	controller = renderer.xr.getController(0);
	controller.addEventListener("select", onSelect);
	scene.add(controller);

When we are hitting a surface, to indicate the surface, we will create a reticle to our scene.

	//Hit-test indicator
	reticle = new Mesh(new RingBufferGeometry(0.15, 0.2, 32).rotateX(-Math.PI / 2), new MeshBasicMaterial());
	reticle.matrixAutoUpdate = false;
	reticle.visible = false;
	scene.add(reticle);

Let's define the onSelect event that we attached to controller. When the select event happen, meaning user decides to place the object and we create it on the chosen location.

function onSelect() {
	if (reticle.visible) {
		const mesh = new Mesh(geometry, phongMaterial);
		mesh.position.setFromMatrixPosition(reticle.matrix);
		mesh.scale.y = Math.random() * 2 + 1;
		scene.add(mesh);
	}
}

Finally in our render function, we will check in every XRFrame if we have an hit-test source to display the reticle on the surface.

function render(timestamp: number, frame: any) {
	if (frame) {
		earth.visible = false;
		const referenceSpace = renderer.xr.getReferenceSpace();
		const session = renderer.xr.getSession();
		if (hitTestSourceRequested === false) {
			session.requestReferenceSpace("viewer").then((referenceSpace) => {
				session.requestHitTestSource({ space: referenceSpace }).then((source) => {
					hitTestSource = source;
				});
			});

			session.addEventListener("end", () => {
				hitTestSourceRequested = false;
				hitTestSource = null;
			});
			hitTestSourceRequested = true;
		}
		if (hitTestSource) {
			const hitTestResults = frame.getHitTestResults(hitTestSource);
			if (hitTestResults.length) {
				const hit = hitTestResults[0];
				reticle.visible = true;
				reticle.matrix.fromArray(hit.getPose(referenceSpace).transform.matrix);
			} else {
				reticle.visible = false;
			}
		}
	}
	renderer.render(scene, camera);
}

To run the code on your device, you have to give access to your camera when prompted.

function onSelect() {
	if (reticle.visible) {
		const mesh = new Mesh(geometry, phongMaterial);
		mesh.position.setFromMatrixPosition(reticle.matrix);
		mesh.scale.y = Math.random() * 2 + 1;
		scene.add(mesh);
	}
}

function render(timestamp: number, frame: any) {
	if (frame) {
		earth.visible = false;
		const referenceSpace = renderer.xr.getReferenceSpace();
		const session = renderer.xr.getSession();
		if (hitTestSourceRequested === false) {
			session.requestReferenceSpace("viewer").then((referenceSpace) => {
				session.requestHitTestSource({ space: referenceSpace }).then((source) => {
					hitTestSource = source;
				});
			});

			session.addEventListener("end", () => {
				hitTestSourceRequested = false;
				hitTestSource = null;
			});
			hitTestSourceRequested = true;
		}
		if (hitTestSource) {
			const hitTestResults = frame.getHitTestResults(hitTestSource);
			if (hitTestResults.length) {
				const hit = hitTestResults[0];
				reticle.visible = true;
				reticle.matrix.fromArray(hit.getPose(referenceSpace).transform.matrix);
			} else {
				reticle.visible = false;
			}
		}
	}
	renderer.render(scene, camera);
}

WebXR Device APIs

Concepts

What are WebXR Device APIs?

Which Devices are Compatible with WebXR?

Which Browsers support WebXR?

How to try out experimental features in Chrome and Edge

What is the Lifecycle of a WebXR Application?

What is XRReferenceSpaceType?

Project

Prerequisites

How to enable VR?

How to enable AR and Hit-test?

How to debug and test your WebXR Application with Chrome Dev Tools?

How to load a 3D Model

Exercise

Troubleshooting

Resources

What could go wrong?

Concepts

WebXR Device APIs

Which Browsers support WebXR?

How to try out experimental features in Chrome and Edge

Resources

What is XRReferenceSpaceType?

What is the Lifecycle of a WebXR Application?

How to debug and test your WebXR Application with Chrome Dev Tools?

How to enable VR?

Which Devices are Compatible with WebXR?

Run the VR experience on your phone

Augmented Reality on Android Devices

How to load a 3D Model

Exercise

Troubleshooting

What are WebXR Device APIs?

What could go wrong?

Project

Prerequisites

How to enable AR and Hit-test?

WebXR Device APIs

Concepts

What are WebXR Device APIs?

Which Devices are Compatible with WebXR?

Which Browsers support WebXR?

hashtagHow to try out experimental features in Chrome and Edge

What is the Lifecycle of a WebXR Application?

What is XRReferenceSpaceType?

Project

hashtagPrerequisites

How to enable VR?

How to enable AR and Hit-test?

How to debug and test your WebXR Application with Chrome Dev Tools?

How to load a 3D Model

hashtagExercise

hashtagTroubleshooting

Resources

What could go wrong?

Concepts

WebXR Device APIs

Which Browsers support WebXR?

hashtagHow to try out experimental features in Chrome and Edge

Resources

What is XRReferenceSpaceType?

What is the Lifecycle of a WebXR Application?

How to debug and test your WebXR Application with Chrome Dev Tools?

How to enable VR?

Which Devices are Compatible with WebXR?

hashtagRun the VR experience on your phone

hashtagAugmented Reality on Android Devices

How to load a 3D Model

hashtagExercise

hashtagTroubleshooting

What are WebXR Device APIs?

What could go wrong?

Project

hashtagPrerequisites

How to enable AR and Hit-test?

How to try out experimental features in Chrome and Edge

Prerequisites

Exercise

Troubleshooting

How to try out experimental features in Chrome and Edge

Run the VR experience on your phone

Augmented Reality on Android Devices

Exercise

Troubleshooting

Prerequisites