{"id":14344,"library":"webvr-polyfill","title":"WebVR Polyfill","description":"The `webvr-polyfill` library provides a comprehensive JavaScript implementation of the WebVR 1.1 specification, designed to ensure WebVR content functions consistently across a wide array of platforms, regardless of native browser or device WebVR support. Its primary function is to inject a WebVR 1.1 API if absent, patch browsers with incomplete or inconsistent implementations, and offer a synthesized `CardboardVRDisplay` on mobile when native support is missing. The current stable version is 0.10.12, with a release cadence that has slowed as the ecosystem transitions towards the WebXR Device API. A key differentiator is its ability to provide a baseline VR experience by abstracting away fragmented native support, including head tracking orientation prediction to minimize motion-to-photon latency and reduce VR sickness. The project aims to allow developers to target the WebVR API without extensive browser-specific workarounds.","status":"maintenance","version":"0.10.12","language":"javascript","source_language":"en","source_url":"https://github.com/immersive-web/webvr-polyfill","tags":["javascript","vr","webvr"],"install":[{"cmd":"npm install webvr-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add webvr-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add webvr-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library uses a default export for its main constructor in ES modules.","wrong":"import { WebVRPolyfill } from 'webvr-polyfill';","symbol":"WebVRPolyfill","correct":"import WebVRPolyfill from 'webvr-polyfill';"},{"note":"For CommonJS environments, the module exports the constructor directly as the default export.","wrong":"const { WebVRPolyfill } = require('webvr-polyfill');","symbol":"WebVRPolyfill","correct":"const WebVRPolyfill = require('webvr-polyfill');"},{"note":"When included via a <script> tag, the `WebVRPolyfill` constructor becomes available as a global variable. No explicit import statement is needed.","symbol":"WebVRPolyfill (Global)","correct":"<script src='webvr-polyfill.js'></script>\n// WebVRPolyfill is now a global variable"}],"quickstart":{"code":"import WebVRPolyfill from 'webvr-polyfill';\n\n// Example configuration (refer to src/config.js for full options)\nconst polyfillConfig = {\n  // Scales the buffer size for rendering. Lower values improve performance.\n  BUFFER_SCALE: 0.5,\n  // Set to true to disable mobile VR display if you only want native VRDisplays.\n  PROVIDE_MOBILE_VRDISPLAY: true\n};\n\n// Instantiate the polyfill before any VR-specific code runs\nconst polyfill = new WebVRPolyfill(polyfillConfig);\n\nlet vrDisplay;\n\nnavigator.getVRDisplays().then(displays => {\n  if (displays.length) {\n    vrDisplay = displays[0];\n    console.log(`Using VRDisplay: ${vrDisplay.displayName}`);\n    console.log(\"WebVR display found or polyfilled. Proceed with VR experience.\");\n    // For a full VR experience, you'd typically integrate with a rendering loop:\n    // vrDisplay.requestAnimationFrame(animate); // requires a 'renderer' and 'animate' function\n  } else {\n    console.log(\"No WebVR displays found. Consider desktop-oriented controls or a non-VR fallback.\");\n  }\n}).catch(error => {\n  console.error(\"Error getting VR displays:\", error);\n});","lang":"javascript","description":"Instantiates the WebVRPolyfill with optional custom configuration, then demonstrates how to query for VR displays using `navigator.getVRDisplays()`, adapting the experience based on whether a VR display is found or synthesized."},"warnings":[{"fix":"Consult the `0.9.40 tag` documentation on GitHub for older versions and review `src/config.js` for current configuration options.","message":"Version 0.10.0 introduced significant internal refactoring, including potential changes to previously 'scope-creeping' functionalities. Code written for versions `<=0.9.x` may require updates.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Ensure you are using `webvr-polyfill@0.10.3` or later, which includes a hotfix for these Chrome regressions. Validate `devicemotion` event handling and coordinate systems in your application.","message":"Chrome versions M65 and M66 introduced regressions in `devicemotion` events, specifically affecting `rotationRate`. M65 broke head tracking due to missing data, and M66 changed `DeviceMotionEvent.rotationRate` values from radians to degrees, impacting calculation accuracy.","severity":"breaking","affected_versions":">=0.10.3"},{"fix":"Adjust `BUFFER_SCALE` to a lower value if experiencing performance issues, especially on lower-end devices. Profile your application to identify bottlenecks.","message":"VR performance is critical; sluggish applications can result from default settings. The `BUFFER_SCALE` configuration property, which defaults to 0.5, can significantly impact performance if set higher.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refer to the `cardboard-vr-display README` on GitHub for detailed information and recommended workarounds regarding iframe usage with the polyfill.","message":"Embedding polyfilled WebVR content within iframes introduces specific concerns and caveats, potentially affecting device motion access and overall functionality due to browser security restrictions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Leverage the polyfill's head tracking orientation prediction feature. Optimize rendering pipelines and JavaScript execution to minimize overall latency. Consider target device capabilities.","message":"High motion-to-photon latency (typically >150ms) can induce VR sickness. While the polyfill provides head tracking orientation prediction, developers should be aware of this potential issue if prediction is insufficient or disabled.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.10.12':75 '1.1':16,47 'abil':97 'absent':50 'abstract':105 'across':25 'aim':128 'allow':130 'api':48,91,136 'array':28 'away':106 'baselin':101 'browser':34,52,140 'browser-specif':139 'cadenc':79 'cardboardvrdisplay':62 'comprehens':10 'consist':24 'content':22 'current':71 'design':18 'develop':131 'devic':36,90 'differenti':94 'ecosystem':85 'ensur':20 'experi':103 'extens':138 'fragment':107 'function':23,41 'head':111 'implement':12,57 'includ':110 'incomplet':54 'inconsist':56 'inject':44 'javascript':11,143 'key':93 'latenc':121 'librari':7 'minim':116 'miss':69 'mobil':64 'motion':118 'motion-to-photon':117 'nativ':33,66,108 'offer':59 'orient':113 'patch':51 'photon':120 'platform':30 'polyfil':2,6 'predict':114 'primari':40 'project':127 'provid':8,99 'reduc':123 'regardless':31 'releas':78 'sick':125 'slow':82 'specif':17,141 'stabl':72 'support':38,67,109 'synthes':61 'target':133 'toward':87 'track':112 'transit':86 'version':73 'vr':102,124,144 'webvr':1,5,15,21,37,46,135,145 'webvr-polyfil':4 'webxr':89 'wide':27 'without':137 'workaround':142","created_at":"2026-04-20T01:59:13.503598+00:00","updated_at":"2026-04-20T01:59:13.503598+00:00","problems":[{"fix":"Upgrade `webvr-polyfill` to version `0.10.3` or higher to include the necessary hotfixes for `devicemotion` event processing.","cause":"Chrome M65/M66 introduced regressions in `devicemotion` event handling, causing missing `rotationRate` data or incorrect units (degrees instead of radians).","error":"Head tracking is broken or erratic in Chrome."},{"fix":"Ensure you are using `webvr-polyfill@0.10.3` or later. This version correctly handles the change in units for `rotationRate` values, preventing rotational inaccuracies.","cause":"This often occurs due to misinterpretation of `DeviceMotionEvent.rotationRate` values. Specifically, Chrome M66 changed the units from radians to degrees.","error":"My VR scene spins uncontrollably or has an incorrect initial orientation."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/immersive-web/webvr-polyfill","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/webvr-polyfill","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}