JavaScript Document pointerlockerror Event

What You’ll Learn

The Document pointerlockerror event fires when locking the pointer fails (technical reasons or permission denied). Learn how to use document.onpointerlockerror, why it does not bubble, how it pairs with requestPointerLock() and pointerlockchange, and five try-it labs.

Introduction

Pointer lock is powerful for games and 3D viewers—and often restricted. If requestPointerLock() is denied, the pointer stays unlocked. Instead you get a pointerlockerror event on document (and, in browsers that return a Promise, a rejection).

MDN documents this as a Document event that is not cancelable and does not bubble. Listening on document is the right place for app-wide error UI alongside pointerlockchange.

Understanding pointerlockerror

A Document event that answers: “Did pointer lock fail?”

• Fires when locking the pointer failed (technical reasons or permission denied).
• Does not bubble — listen on document (unlike fullscreenerror’s Element-then-Document path).
• Not cancelable — you cannot force a lock with preventDefault().
• Event type — a plain Event (no rich error code on the event itself).
• Handler — document.onpointerlockerror or document.addEventListener("pointerlockerror", ...).
• Limited availability on MDN (not Baseline)—test carefully.

📝 Syntax

Use the event name with addEventListener, or set the handler property on document:

addEventListener("pointerlockerror", (event) => { });

onpointerlockerror = (event) => { };

Event type

A generic Event. Not cancelable and does not bubble.

MDN Document example

const para = document.querySelector("p");

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

// or
document.onpointerlockerror = (event) => {
  console.log("Error locking pointer");
};

Success vs failure path

⚠️ Why Pointer Lock Requests Fail

• No user gesture — call from a click/key handler, not a bare timer.
• Permission denied — the browser or user may refuse pointer lock.
• Unsupported context — older browsers, some embedders, or restricted environments.
• Technical issues — MDN notes failures for technical reasons as well as denial.
• Exit failures — the Pointer Lock overview also mentions errors from exitPointerLock().

See MDN’s Pointer Lock API guide and the pointerlockerror page for details.

⚖️ pointerlockerror vs pointerlockchange

Examples Gallery

Examples follow MDN Document: pointerlockerror event and listen on document. Some labs intentionally trigger failures (for example calling without a user gesture).

const para = document.querySelector("p");

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

Error locking pointer

const el = document.getElementById("game");
const out = document.getElementById("out");

document.onpointerlockerror = () => {
  out.textContent = "pointerlockerror: could not lock pointer";
};

document.getElementById("bad").addEventListener("click", () => {
  // May still fail in unsupported / restricted environments
  el.requestPointerLock();
});

pointerlockerror: could not lock pointer

const el = document.getElementById("game");
const out = document.getElementById("out");

document.addEventListener("pointerlockerror", () => {
  out.textContent = "Event: pointerlockerror (on document)";
});

document.getElementById("go").addEventListener("click", () => {
  el.requestPointerLock().catch((err) => {
    out.textContent =
      "Promise rejected: " + (err && err.message ? err.message : String(err));
  });
});

Event: pointerlockerror (on document)
(and/or Promise rejected with a message)

const el = document.getElementById("game");
const out = document.getElementById("out");

document.addEventListener("pointerlockerror", () => {
  out.textContent = "pointerlockerror (likely no user gesture / denied)";
});

document.getElementById("arm").addEventListener("click", () => {
  out.textContent = "Calling requestPointerLock in 500ms without a gesture...";
  setTimeout(() => {
    el.requestPointerLock().catch(() => {
      out.textContent += "\nPromise also rejected.";
    });
  }, 500);
});

Calling requestPointerLock in 500ms without a gesture...
pointerlockerror (likely no user gesture / denied)
Promise also rejected.

const el = document.getElementById("game");
const msg = document.getElementById("msg");

document.addEventListener("pointerlockerror", () => {
  msg.textContent =
    "Pointer lock blocked here. Using mouse-move aiming without lock.";
  el.classList.add("is-fallback");
});

document.addEventListener("pointerlockchange", () => {
  if (document.pointerLockElement) {
    msg.textContent = "Pointer lock OK";
    el.classList.remove("is-fallback");
  }
});

document.getElementById("go").addEventListener("click", () => {
  el.requestPointerLock();
});

Pointer lock blocked here. Using mouse-move aiming without lock.

🚀 Common Use Cases

• Toast / banner when a “Lock pointer” button is denied.
• Falling back to regular mouse-move aiming for games.
• Logging analytics for pointer-lock permission failures.
• Teaching why user gestures matter for privileged APIs.
• One Document listener covering lock errors for every game surface.

🔧 How It Works

📝 Notes

• MDN: Limited availability (not Baseline)—test the browsers you support.
• Not Deprecated, Experimental, or Non-standard—no status banner required.
• Not cancelable and does not bubble; pair with Promise .catch() when available.
• Listen on document only—this is not an Element-then-Document pair.
• Related learning: pointerlockchange, exitPointerLock(), pointerLockElement, requestPointerLock(), JavaScript hub.

💡 Best Practices