JavaScript Document pointerlockerror Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event
Decorative image with the word POINTERLOCKERROR

Definition

In JavaScript, the Document pointerlockerror event fires when locking the pointer failed — for technical reasons or because permission was denied (MDN). It is not cancelable and does not bubble.

Register a listener with addEventListener. Check readiness and browser support before you rely on this event.

Syntax

Listen for pointerlockerror. Start with this line.

JavaScript
addEventListener("pointerlockerror", fn)
CallWhat it does
addEventListener("pointerlockerror", fn)Primary signature.

Built into the browser. Listen with document.addEventListener("pointerlockerror", …) — no import required.

Library declarations
JavaScript
addEventListener("pointerlockerror", fn)

Parameters

ParameterDescription
Listener on documentRequired. Event does not bubble (MDN)
Promise catch (if returned)Optional. Some engines return a Promise from requestPointerLock()

Return Value

Return ValueDescription
*Fires as a Document event (listener receives the Event object).

JavaScript Examples

Example 1 — Listen on document

MDN style: handle lock failures with a Document listener.

JavaScript
document.addEventListener("pointerlockerror", (event) => {
  console.log("Error locking pointer");
  console.log(event.type); // "pointerlockerror"
});

console.log("pointerlockerror listener attached");
Try It Yourself

How It Works

  1. Listen on document. MDN: the event does not bubble.
  2. Log on failure. Useful while learning; apps show user-facing text.
  3. Event type. A generic Event — not cancelable.
  4. Idle until fail. Nothing logs until a lock request actually fails.

Example 2 — Request Lock and Handle Error

Pair pointerlockerror with a click-based requestPointerLock().

JavaScript
const stage = document.getElementById("stage");
const btn = document.getElementById("lock");

document.addEventListener("pointerlockerror", () => {
  console.log("pointerlockerror fired");
});

document.addEventListener("pointerlockchange", () => {
  console.log("locked?", !!document.pointerLockElement);
});

btn.addEventListener("click", () => {
  stage.requestPointerLock();
});
Try It Yourself

How It Works

  1. Listen for error and change. Cover both success and failure paths.
  2. Request on click. User gesture improves success odds.
  3. On failure. pointerlockerror fires; lock state stays unlocked.
  4. On success. pointerlockchange fires and pointerLockElement is set.

Example 3 — Detect Before Offering Lock

Avoid useless clicks when Pointer Lock is unsupported.

JavaScript
const ok =
  "pointerLockElement" in document &&
  typeof document.documentElement.requestPointerLock === "function";

console.log("Pointer Lock usable:", ok);

if (!ok) {
  console.log("Hide the button — lock would fail");
}
Try It Yourself

How It Works

  1. Probe the property. "pointerLockElement" in document is a quick signal.
  2. Check the method. Confirm requestPointerLock exists.
  3. Gate the UI. Only show the control when both checks pass.
  4. Still listen for errors. Even “supported” requests can fail at runtime.
Compatibility

Browser Support

Document pointerlockerror is part of the Pointer Lock API. MDN marks it Limited availability (not Baseline). It is not Deprecated, Experimental, or Non-standard — still feature-detect in production.

✓ Limited availability · Not Baseline

Document pointerlockerror

Fires when locking the pointer failed. Listen on document — the event does not bubble.

Limited Feature-detect required
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
pointerlockerror Limited

Bottom line: Support mirrors Pointer Lock. Always feature-detect, require a user gesture, and pair with pointerlockchange for the success path.

Frequently Asked Questions

It fires when locking the pointer failed — for technical reasons or because permission was denied (MDN). Listen on document; the event does not bubble.
No. MDN does not mark Document pointerlockerror as Deprecated, Experimental, or Non-standard. It has Limited availability (not Baseline), so feature-detect and test the browsers you care about.
Common reasons: no user gesture, unsupported browser or context, permission denial, or other technical restrictions. Listen for pointerlockerror and optionally handle a Promise rejection when requestPointerLock returns a Promise.
No. MDN states this event is not cancelable and does not bubble. Listen on document.
No. Unlike fullscreenerror (Element then Document), MDN documents pointerlockerror as a Document event that does not bubble.
Success path: pointerlockchange fires and pointerLockElement is non-null. Failure path: pointerlockerror fires instead and the pointer stays unlocked.

Next: prerenderingchange

Learn the Document event that fires when a prerendered page is activated.

prerenderingchange tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document pointerlockchange Event JavaScript Document prerenderingchange Event