Web/API/XRSystem

Secure contextThis feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The WebXR Device API interface XRSystem provides methods which let you get access to an XRSession object representing a WebXR session. With that XRSession in hand, you can use it to interact with the Augmented Reality (AR) or Virtual Reality (VR) device.

Properties

While XRSystem directly offers no properties, it does inherit properties from its parent interface, EventTarget.

Methods

In addition to inheriting methods from its parent interface, EventTarget, the XRSystem interface includes the following methods:

isSessionSupported() ': Returns a promise which resolves to true if the browser supports the given XRSessionMode. Resolves to false if the specified mode isn't supported.
requestSession() ': Returns a promise that resolves to a new XRSession with the specified XRSessionMode.

Events

devicechange ': Sent when the set of available XR devices has changed. Also available using the ondevicechange event handler.

Usage notes

This interface was previously known as simply XR in earlier versions of the specification; if you see references to XR in code or documentation, simply replace that with XRSystem.

Examples

The following example shows how to use both isSessionSupported() and requestSession().

if (navigator.xr) {
  immersiveButton.addEventListener("click", onButtonClicked);
  navigator.xr.isSessionSupported('immersive-vr')
  .then((isSupported) => {
    if (isSupported) {
      immersiveButton.disabled = false;
    } else {
      immersiveButton.disabled = true;
    }
  });
}

function onButtonClicked() {
  if (!xrSession) {
    navigator.xr.requestSession('immersive-vr')
    .then((session) => {
      // onSessionStarted() not shown for reasons of brevity and clarity.
      onSessionStarted(session);
    });
  } else {
    // Shut down the already running XRSession
    xrSession.end()
    .then(() => {
      // Since there are cases where the end event is not sent, call the handler here as well.
      onSessionEnded();
    });
  }
}

This code starts by checking to see if WebXR is available by looking for the navigator.xr property. If it's found, we know WebXR is present, so we proceed by establishing a handler for the button which the user can click to toggle immersive VR mode on and off.

However, we don't yet know if the desired immersive mode is available. To determine this, we call isSessionSupported(), passing it the desired session option before enabling the button, immersiveButton, which the user can then use to switch to immersive mode only if immersive VR mode is available. If immersive VR isn't available, the button is disabled to prevent its use.

The onButtonClicked() function checks to see if there's already a session running. If there isn't, we use requestSession() to start one and, once the returned promise resolves, we call a function onSessionStarted() to set up our session for rendering and so forth.

If, on the other hand, there is already an ongoing XR session, we instead call end() to end the current session. When the current session ends, the end event is sent, so set xrSession to null in its handler to record the fact that we no longer have an ongoing session. That way, if the user clicks the button again, a new session will start.

Specifications

Specification	Status	Comment
WebXR Device APIThe definition of 'XRSystem' in that specification.	Working Draft	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`XRSystem` Experimental'	Chrome Full support 79 Alternate Name' Full support 79 Alternate Name' Alternate Name' Uses the non-standard name: `XR`	Edge Full support 79 Alternate Name' Full support 79 Alternate Name' Alternate Name' Uses the non-standard name: `XR`	Firefox No support No	IE No support No	Opera No support No	Safari No support No	WebView Android No support No	Chrome Android Full support 79 Alternate Name' Full support 79 Alternate Name' Alternate Name' Uses the non-standard name: `XR`	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android Full support 11.2 Alternate Name' Full support 11.2 Alternate Name' Alternate Name' Uses the non-standard name: `XR`
`devicechange` event Experimental'	Chrome Full support 79	Edge Full support 79	Firefox No support No	IE No support No	Opera No support No	Safari No support No	WebView Android No support No	Chrome Android Full support 79	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android Full support 11.2
`isSessionSupported()` Experimental'	Chrome Full support 79	Edge Full support 79	Firefox No support No	IE No support No	Opera No support No	Safari No support No	WebView Android No support No	Chrome Android Full support 79	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android Full support 11.2
`ondevicechange` Experimental'	Chrome Full support 79	Edge Full support 79	Firefox No support No	IE No support No	Opera No support No	Safari No support No	WebView Android No support No	Chrome Android Full support 79	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android Full support 11.2
`requestSession()` Experimental'	Chrome Full support 79	Edge Full support 79	Firefox No support No	IE No support No	Opera No support No	Safari No support No	WebView Android No support No	Chrome Android Full support 79	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android Full support 11.2

Legend

Full support: Full support
No support: No support
Experimental. Expect behavior to change in the future.': Experimental. Expect behavior to change in the future.
Uses a non-standard name.': Uses a non-standard name.

XRSystem by Mozilla Contributors is licensed under CC-BY-SA 2.5.