XRSystem: requestSession()

The XRSystem interface's requestSession() method returns a promise which resolves to an XRSession object through which you can manage the requested type of WebXR session.

While only one immersive VR session can be active at a time, multiple inline sessions can be in progress at once.

Syntax

navigator.xr.requestSession(mode, options)

Parameters

mode

A String defining the XR session mode. The supported modes are:

  • immersive-ar: The session's output will be given exclusive access to the immersive device, but the rendered content will be blended with the real-world environment. The session's environmentBlendMode indicates the method to be used to blend the content together.
  • immersive-vr: Indicates that the rendered session will be displayed using an immersive XR device in VR mode; it is not intended to be overlaid or integrated into the surrounding environment. The environmentBlendMode is expected to be opaque if possible, but might be additive if the hardware requires it.
  • inline: The output is presented inline within the context of an element in a standard HTML document, rather than occupying the full visual space. Inline sessions can be presented in either mono or stereo mode, and may or may not have viewer tracking available. Inline sessions don't require special hardware and should be available on any user agent offering WebXR API support.
options Optional
An object to configure the XRSession. If none are included, the device will use a default feature configuration for all options. For more information, see Session features below.
  • requiredFeatures Optional: An array of values which the returned XRSession must support.
  • optionalFeatures Optional: An array of values identifying features which the returned XRSession may optionally support.
  • domOverlay Optional: An object with a required root property that specifies the overlay element that will be displayed to the user as the content of the DOM overlay.

Return value

A Promise that resolves with an XRSession object if the device and user agent support the requested mode and features.

Exceptions

This method doesn't throw true exceptions; instead, it rejects the returned promise, passing into it a DOMException whose name is one of the following:

InvalidStateError
The requested session mode is immersive-vr but there is already an immersive VR session either currently active or in the process of being set up. There can only be one immersive VR session at a time.
NotSupportedError
There is no WebXR-compatible device available, or the device does not support the specified sessionMode; this can also be thrown if any of the required options are unsupported.
SecurityError

Permission to enter the specified XR mode is denied. This can happen for a number of reasons, which are covered in more detail in Permissions and security in WebXR Device API.

Session features

Immersive sessions

All immersive (both immersive-vr and immersive-ar)   sessions support both the viewer and local reference spaces.

Because immersive sessions are required to support the local reference space, any request to open an immersive XRSession is required to obtain explicit or implicit user consent.

To request the use of a DOM overlay element, add the string dom-overlay to either requiredFeatures or optionalFeatures.

Inline sessions

All inline WebXR sessions support the viewer reference space.

Security requirements

Each reference space or feature type has minimum safety requirements. By session type, those are:

Reference space type User consent rquirement Feature policy requirement
bounded-floor Always required xr-spatial-tracking
local Always required for inline sessions xr-spatial-tracking
local-floor Always required xr-spatial-tracking
unbounded Always required xr-spatial-tracking
viewer Always required

Examples

Creating an immersive VR session

The following example calls requestSession() requesting an "immersive-vr" session. If the Promise resolves, it sets up a session and initiates the animation loop.

navigator.xr.requestSession("immersive-vr")
.then((xrSession) => {
  xrSession.addEventListener('end', onXRSessionEnded);
  // Do necessary session setup here.
  // Begin the session’s animation loop.
  xrSession.requestAnimationFrame(onXRAnimationFrame);
}).catch(function(error) {
  // "immersive-vr" sessions are not supported
  console.warn("'immersive-vr' isn't supported, or an error occurred activating VR!");
});

Verifying WebXR support and using a button to start VR mode

The following example shows how to use both isSessionSupported() and requestSession(). First, it checks to see if WebXR is available by verifying the existence of navigator.xr. Next, it calls isSessionSupported(), passing it the desired session option before enabling controls for entering XR. Adding controls is a necessary step because entering XR requires a user action. Finally, the onButtonClicked() method calls requestSession() using the same session option passed to isSessionSupported().

if (navigator.xr) {
  navigator.xr.isSessionSupported('immersive-vr')
  .then((isSupported) => {
    if (isSupported) {
      immersiveButton.addEventListener('click', onButtonClicked);
      immersiveButton.textContent = 'Enter XR';
      immersiveButton.disabled = false;
    } else {
      console.log("WebXR doesn't support immersive-vr mode!");
    }
  });
} else {
  console.log("WebXR is not available!");
}

function onButtonClicked() {
  if (!xrSession) {
    navigator.xr.requestSession('immersive-vr')
    .then((session) => {
      xrSession = session;
      // onSessionStarted() not shown for reasons of brevity and clarity.
      onSessionStarted(xrSession);
    });
  } else {
    // Button is a toggle button.
    xrSession.end().then(() => xrSession = null);
  }
}

Requesting a session with required features

Require an unbounded experience in which the user is able to freely move around their physical environment:

navigator.xr.requestSession('immersive-vr', { requiredFeatures: ['unbounded'] })

Requesting a session with a DOM overlay

navigator.xr.requestSession(‘immersive-ar’, {
  optionalFeatures: ["dom-overlay"],
  domOverlay: {
    root: document.getElementById("xr-overlay")
  }
}

Specifications

Specification
WebXR Device API
# dom-xrsystem-requestsession

Browser compatibility

BCD tables only load in the browser