XRSession

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

Draft
This page is not complete.

The WebXR Device API's XRSession interface represents an ongoing XR session, providing methods and properties used to interact with and control the session. To open a WebXR session, use the XR interface's requestSession() method.

With XRSession methods, you can poll the viewer's position and orientation (the XRViewerPose), gather information about the user's environment, and present imagery to the user. XRSession supports both inline and immersive virtual and augmented reality modes.

Properties

In addition to the properties listed below, XRSession inherits properties from its parent interface, EventTarget.

environmentBlendMode  Read only

Returns this session's blend mode which denotes how much of the real-world environment is visible through the XR device and how the device will blend the device imagery with it.

Note: environmentBlendMode() is part of the WebXR Augmented Reality Module, which has not been completed.

inputSources Read only
Returns a list of this session's XRInputSources, each representing an input device used to control the camera and/or scene.
renderState Read only
An XRRenderState object which contains options affecting how the imagery is rendered. This includes things such as the near and far clipping planes (distances defining how close and how far away objects can be and still get rendered), as well as field of view information.
visibilityState Read only
A DOMString whose value is one of those found in the XRVisibilityState enumerated type, indicating whether or not the session's imagery is visible to the user, and if so, if it's being rendered blurred.

Methods

XRSession provides the following methods in addition to those inherited from its parent interface, EventTarget.

cancelAnimationFrame()
Removes a callback from the animation frame painting callback from XRSession's set of animation frame rendering callbacks, given the identifying handle returned by a previous call to requestAnimationFrame().
end()
Ends the WebXR session. Returns a promise which resolves when the session has been shut down.
requestAnimationFrame()
Schedules the specified method to be called the next time the user agent is working on rendering an animation frame for the WebXR device. Returns an integer value which can be used to identify the request for the purposes of canceling the callback using cancelAnimationFrame(). This method is comparable to the Window.requestAnimationFrame method.
requestReferenceSpace()
Requests that a new XRReferenceSpace of the specified type be created. Returns a promise which resolves with the XRReferenceSpace or XRBoundedReferenceSpace which was requested, or throws a NotSupportedError if the requested space type isn't supported by the device.
updateRenderState()
Updates the properties of the session's render state to match the values specified in the specified XRRenderStateInit dictionary. Any properties not included in the given dictionary are left unchanged from their current values.

Events

The following events are delivered to XRSession objects.

Event Description
end Sent to the XRSession object after the WebXR session has ended and all hardware-related functions have completed. The event is represented by an object of type XRSessionEvent.
Also available through the onend event handler property.
inputsourceschange An event of type XRInputSourcesChangeEvent sent to the XRSession when the list of active XR input sources has changed.
Also available through the oninputsourceschange event handler property.
select An event of type XRInputSourceEvent which is sent to the session when one of the session's input sources has completed a primary action. This generally corresponds to the user pressing a trigger, touchpad, or button, speaks a command, or performs a recognizable gesture. The select event is sent in after the selectstart event is sent and immediately before the selectend event is sent.
Also available through the onselect event handler property.
selectend An event of type XRInputSourceEvent which gets sent to the session object when one of its input devices finishes its primary action or gets disconnected while in the process of handling a primary action. For example: for button or trigger actions, this means the button has been released; for spoken commands, it means the user has finished speaking. This is the last of the three select* events to be sent.
Also available through the onselectend event handler property.
selectstart An event of type XRInputSourceEvent which is sent to the session object when one of its input devices is first engaged by the user in such a way as to cause the primary action to begin. This is the first of the session* event to be sent.
Also available through the onselectstart event handler property.
visibilitychange An XRSessionEvent which is sent to the session when its visibility state as indicated by the visibilityState changes.
Also available through the onvisibilitychange event handler property.

Example

This example establishes a new XRSession in inline mode so that it can be displayed within an HTML element, avoiding the need for a dedicated AR or VR viewing device such as a headset.

---> EXAMPLE NOT YET TESTED IN THIS STATE <---

const XR = navigator.xr;

if (XR) {
  XR.requestSession("inline").then((xrSession) => {
    xrSession.requestReferenceSpace("local").then((xrReferenceSpace) => { 
      xrSession.requestAnimationFrame((time, xrFrame) => {
        let viewer = xrFrame.getViewerPose(xrReferenceSpace);

        gl.bindFramebuffer(xrWebGLLayer.framebuffer);
        
        for (xrView of viewer.views) {
          let xrViewport = xrWebGLLayer.getViewport(xrView);
          gl.viewport(xrViewport.x, xrViewport.y,
                      xrViewport.width, xrViewport.height);
        }
      });
    });
  });
} else {
  /* WebXR is not available */
}

Specifications

Specification Status Comment
WebXR Device API
The definition of 'XRSession' in that specification.
Working Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
XRSessionChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
cancelAnimationFrame()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
end()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
end eventChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
environmentBlendModeChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
inputSourcesChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
inputsourceschange eventChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
onendChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
oninputsourceschangeChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
onselectChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
onselectendChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
onselectstartChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
onvisibilitychangeChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
renderStateChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
requestAnimationFrame()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
requestReferenceSpace()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
select eventChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
selectend eventChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
selectstart eventChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
updateRenderState()Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
visibilitychange eventChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
visibilityStateChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

No support  
No support