Skip to content
A JavaScript implementation of a WebVR 1.1 VRDisplay
Branch: master
Clone or download
Latest commit de59375 Dec 11, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist 1.0.16 Dec 11, 2018
examples Disable Sensors if loading example within an iframe -- details in REA… Jul 11, 2018
src Optimize rotate instructions SVG Nov 15, 2018
third_party/three.js Remove three source tree, change to third_party structure with built … Oct 10, 2017
.babelrc Use ES6 imports to lay groundwork for including ES6 dependencies in n… Jan 9, 2018
.gitignore Add build file Nov 2, 2017
.npmignore Do not ignore build artifacts, since now pointing to built file as 'm… Feb 2, 2018
.travis.yml Remove deprecated node.js CI support, upgrade webvr-polyfill-dpdb to … Oct 17, 2018 Add contributing Oct 11, 2017
LICENSE Ensure that the wglu-preserve-state license is in header of both buil… May 31, 2017 Link to issue in readme Aug 3, 2018
index.html Add new ADDITIONAL_VIEWERS and DEFAULT_VIEWER options to config and d… May 16, 2018
package-lock.json 1.0.16 Dec 11, 2018
package.json 1.0.16 Dec 11, 2018
rollup.config.js Use ES6 imports to lay groundwork for including ES6 dependencies in n… Jan 9, 2018


Build Status Build Status

A JavaScript implementation of a WebVR 1.1 VRDisplay. This is the magic behind rendering distorted stereoscopic views for browsers that do not support the WebVR API with the webvr-polyfill.

Unless you're building a WebVR wrapper, you probably want to use webvr-polyfill directly rather than this. This component does not polyfill interfaces like VRFrameData and navigator.getVRDisplays, and up to the consumer, although trivial (see examples).

How It Works

As of 1.0.4, CardboardVRDisplay uses RelativeOrientationSensor for orientation tracking, falling back to DeviceMotionEvents using sensor fusion and pose prediction. RelativeOrientationSensor is a new API (read more about the new Sensors on the web) first implemented in Chrome M63. This API uses the new Feature Policy specification which allows developers to selectively enable or disable browser features.

It can also render in stereo mode, and includes mesh-based lens distortion. This display also includes user interface elements in VR mode to make the VR experience more intuitive, including:

  • A gear icon to select your VR viewer.
  • A back button to exit VR mode.
  • An interstitial which only appears in portrait orientation, requesting you switch into landscape orientation (if orientation lock is not available).


By default, main frames and same-origin iframes have access to Sensor APIs, but cross-origin iframes must specify feature policy and allow gyroscope and accelerometer features. If your experience is attempting to use the native WebXR Device API in an iframe, you'll have to specify that feature as well (WebXR's feature name may change). All of these features require HTTPS to function, except for localhost, where HTTP is allowed.

<iframe src="" allow="gyroscope; accelerometer; xr"></iframe>

While devicemotion is a fallback for Sensors, eventually devicemotion will be behind the same Feature Policy as Sensors and it is encouraged to adhere to these policies in the meantime. If the Feature Policy for Sensors is denied, CardboardVRDisplay will not always attempt to fall back to devicemotion. Using Feature Policies now will guarantee a more future-proof experience.


  • On iOS, cross-origin iframes do not have access to the devicemotion events. The CardboardVRDisplay however does respond to events passed in from a parent frame via postMessage. See the iframe example to see how the events must be formatted.
  • Chrome M63 supports Sensors, although not the corresponding Feature Policy until Chrome M65. This results in Chrome M63/M64 only supporting Sensors in main frames, and these browsers will fall back to using devicemotion if in iframes.
  • Using Sensors in a cross-origin iframe requires the frame to be in focus. In builds of Chrome prior to M69, this logic is erroneously reversed. If loading content via cross-origin iframe, you can disable Sensors, triggering the devicemotion fallback with this hacky workaround. More info in #27.

Magic Window

It is possible to have a magic window using a VRDisplay that isn't 100% width/height of the window, and can jump into fullscreen WebVR. See the magic window for usage.


$ npm install --save cardboard-vr-display

Browser Support

Should support most modern browsers (IE11 is missing a few, for example) and requires ES5 JavaScript support. If you want to support a non-ES5 browser, or browser lacking some DOM globals, you must use a transformation or provide polyfills to support older environments.

Globals required:

Additionally, WebGL support, devicemotion events, and common browser globals (window, navigator, document) are also required in the environment.


cardboard-vr-display exposes a constructor for a CardboardVRDisplay that takes a single options configuration, detailed below. Check out running the demo to try the different options.

import CardboardVRDisplay from 'cardboard-vr-display';

// Default options
const options = {
  // Optionally inject custom Viewer parameters as an option. Each item
  // in the array must be an object with the following properties; here is
  // an example of the built in CardboardV2 viewer:
  // {
  //   id: 'CardboardV2',
  //   label: 'Cardboard I/O 2015',
  //   fov: 60,
  //   interLensDistance: 0.064,
  //   baselineLensDistance: 0.035,
  //   screenLensDistance: 0.039,
  //   distortionCoefficients: [0.34, 0.55],
  //   inverseCoefficients: [-0.33836704, -0.18162185, 0.862655, -1.2462051,
  //     1.0560602, -0.58208317, 0.21609078, -0.05444823, 0.009177956,
  //     -9.904169E-4, 6.183535E-5, -1.6981803E-6]
  // }
  // Added in 1.0.12.

  // Select the viewer by ID. If unspecified, defaults to 'CardboardV1'.
  // Added in 1.0.12.

  // By default, on mobile, a wakelock is necessary to prevent the device's screen
  // from turning off without user input. Disable if you're keeping the screen awake through
  // other means on mobile. A wakelock is never used on desktop.
  // Added in 1.0.3.

  // Whether or not CardboardVRDisplay is in debug mode. Logs extra
  // messages. Added in 1.0.2.
  DEBUG: false,

  // The URL to JSON of DPDB information. By default, uses the data
  // from; if left
  // falsy, then no attempt is made.
  // Added in 1.0.1
  DPDB_URL: '',

  // Complementary filter coefficient. 0 for accelerometer, 1 for gyro.
  K_FILTER: 0.98,

  // How far into the future to predict during fast motion (in seconds).

  // Flag to disabled the UI in VR Mode.

  // Flag to disable the instructions to rotate your device.

  // Enable yaw panning only, disabling roll and pitch. This can be useful
  // for panoramas with nothing interesting above or below.
  YAW_ONLY: false,

  // Scales the recommended buffer size reported by WebVR, which can improve
  // performance.
  // UPDATE(2016-05-03): Setting this to 0.5 by default since 1.0 does not
  // perform well on many mobile devices.

  // Allow VRDisplay.submitFrame to change gl bindings, which is more
  // efficient if the application code will re-bind its resources on the
  // next frame anyway. This has been seen to cause rendering glitches with
  // THREE.js.
  // Dirty bindings include: gl.FRAMEBUFFER_BINDING, gl.CURRENT_PROGRAM,
  // and gl.TEXTURE_BINDING_2D for texture unit 0.

const display = new CardboardVRDisplay(options);

function MockVRFrameData () {
  this.leftViewMatrix = new Float32Array(16);
  this.rightViewMatrix = new Float32Array(16);
  this.leftProjectionMatrix = new Float32Array(16);
  this.rightProjectionMatrix = new Float32Array(16);
  this.pose = null;

const frame = new (window.VRFrameData || MockVRFrameData)();

display.isConnected; // true

frame.rightViewMatrix; // Float32Array
frame.pose; // { orientation, position }


  • npm install: installs the dependencies.
  • npm run build: builds the distributable.
  • npm run watch: watches src/ for changes and rebuilds on change.

Running The Demo

View the example to see a demo running the CardboardVRDisplay. This executes a minimal WebVR 1.1 polyfill and parses query params to inject configuration parameters. View some premade links at index.html. For example, to set the buffer scale to 1.0 and limit rotation to yaw, go to []. View all config options at src/options.js.


This program is free software for both commercial and non-commercial use, distributed under the Apache 2.0 License.

You can’t perform that action at this time.