JavaScript Document pointerlockchange Event

Beginner
5 min read
Updated: Nov 2026
3 examples
Event

Definition

The Document pointerlockchange event fires when the pointer is locked or unlocked (MDN). In the handler, read Document.pointerLockElement to see whether lock is active and which element owns it.

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

Syntax

Listen for pointerlockchange. Start with this line.

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

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

Library declarations
JavaScript
addEventListener("pointerlockchange", fn)

Parameters

ParameterDescription
Listener on documentRequired. Event does not bubble (MDN)
pointerLockElementRequired. Locked target, or null

Return Value

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

JavaScript Examples

Example 1 — Listen on document

MDN style: after the change, read pointerLockElement to know lock state.

JavaScript
document.addEventListener("pointerlockchange", (event) => {
  if (document.pointerLockElement) {
    console.log("The pointer is locked to:", document.pointerLockElement);
  } else {
    console.log("The pointer is not locked");
  }
});

console.log("Listener attached");
Try It Yourself

How It Works

  1. Listen on document. MDN: the event does not bubble.
  2. Check pointerLockElement. Non-null → locked; null → unlocked.
  3. Log the target. Useful while learning the API.
  4. Update UI next. In games, start or stop look controls here.

Example 2 — Toggle Pointer Lock

Lock with requestPointerLock(), unlock with exitPointerLock() — usually from a click.

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

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

btn.addEventListener("click", () => {
  if (document.pointerLockElement) {
    document.exitPointerLock();
  } else {
    stage.requestPointerLock();
  }
});
Try It Yourself

How It Works

  1. Pick a stage element. That node becomes the lock target.
  2. On click. If already locked, exit; otherwise request lock.
  3. Need a gesture. Calling lock without a click often fails.
  4. Confirm via the event. pointerlockchange reports the new state.

Example 3 — Feature Detection

Check support before offering a lock button.

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

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

if (!ok) {
  console.log("Hide or disable the lock control");
}
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. Combine both. Only then treat the API as usable.
  4. Degrade gracefully. Hide the control when support is missing.

Browser Support

Document pointerlockchange 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 pointerlockchange

Fires when the pointer is locked or unlocked. Read document.pointerLockElement for state.

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
pointerlockchange Limited

Bottom line: Works in many desktop browsers used for games, but support and policy vary. Always feature-detect, require a user gesture, and handle pointerlockerror.

Frequently Asked Questions

It fires when the pointer is locked or unlocked. In the handler, check document.pointerLockElement: if it is non-null the pointer is locked to that element; if null the pointer is not locked (MDN).
No. MDN does not mark it Deprecated, Experimental, or Non-standard. It has Limited availability (not Baseline), so feature-detect and test the browsers you care about.
No. MDN states the event is not cancelable and does not bubble. Listen on document.
Call element.requestPointerLock() from a user gesture to lock. Call document.exitPointerLock() or let the user press Esc to unlock. Update UI on pointerlockchange.
Listen for the pointerlockerror event on document. Failures often happen without a user gesture, in unsupported browsers, or when the browser denies permission.
Games and 3D viewers need unlimited mouse movement without hitting the screen edge. Locked input delivers movementX / movementY deltas instead of a visible cursor.

Next: pointerlockerror

Learn the Document event that fires when a pointer lock request fails.

pointerlockerror 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.

11 people found this page helpful