JavaScript Document pointerlockchange Event

What You’ll Learn

The Document pointerlockchange event fires when the pointer is locked or unlocked. Learn how to read document.pointerLockElement, how to lock with requestPointerLock() and unlock with exitPointerLock(), and five try-it labs.

Introduction

First-person games and 3D viewers need the mouse to keep moving even when the cursor would hit the edge of the screen. The Pointer Lock API hides the cursor and delivers continuous movementX / movementY deltas.

pointerlockchange is the Document signal that lock status already flipped. Update button labels, pause the game when the user presses Esc, or start reading movement events only while locked. MDN marks it Limited availability (not Baseline)—feature-detect and test.

Understanding pointerlockchange

A Document event that answers: “Did pointer lock just turn on or off?”

• Fires when the pointer is locked or unlocked.
• Does not encode lock vs unlock — read document.pointerLockElement.
• Not cancelable and does not bubble (MDN).
• Event type — a plain Event.
• Handler — document.onpointerlockchange or document.addEventListener("pointerlockchange", ...).
• Limited availability on MDN (not Baseline)—test carefully.

📝 Syntax

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

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

onpointerlockchange = (event) => { };

Event type

A generic Event. Not cancelable. Does not bubble.

Related Pointer Lock pieces

🔁 Locked vs Unlocked

By the time your handler runs, the mode has already changed. Use this MDN pattern:

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

• document.pointerLockElement non-null → pointer is locked to that element.
• null → unlocked (Esc, exitPointerLock(), or never locked).

⚖️ Pointer lock vs fullscreen

Games often use both together: fullscreen for immersion, pointer lock for camera look.

Examples Gallery

Examples follow MDN Document: pointerlockchange event. Try-it labs need a real browser click—some embedded previews block pointer lock.

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

The pointer is locked to: [object HTMLCanvasElement]
The pointer is not locked

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

The pointer is not locked

const canvas = document.getElementById("game");
const status = document.getElementById("status");
const unlockBtn = document.getElementById("unlock");

function syncUi() {
  const locked = Boolean(document.pointerLockElement);
  status.textContent = locked ? "Pointer locked (Esc to exit)" : "Click canvas to lock";
  unlockBtn.disabled = !locked;
}

document.addEventListener("pointerlockchange", syncUi);

canvas.addEventListener("click", () => {
  if (!document.pointerLockElement) {
    canvas.requestPointerLock();
  }
});

unlockBtn.addEventListener("click", () => {
  document.exitPointerLock();
});

syncUi();

Click canvas to lock
Pointer locked (Esc to exit)

const canvas = document.getElementById("game");
const note = document.getElementById("note");

const canLock =
  typeof canvas.requestPointerLock === "function" &&
  typeof document.exitPointerLock === "function";

if (!canLock) {
  note.textContent = "Pointer Lock API not available in this environment.";
} else {
  note.textContent = "Pointer Lock API looks available. Click the canvas.";
  document.addEventListener("pointerlockchange", () => {
    note.textContent = document.pointerLockElement
      ? "Locked"
      : "Unlocked";
  });
  canvas.addEventListener("click", () => {
    canvas.requestPointerLock();
  });
}

Pointer Lock API looks available. Click the canvas.

const canvas = document.getElementById("game");
const out = document.getElementById("out");
let yaw = 0;
let pitch = 0;

document.addEventListener("pointerlockchange", () => {
  out.textContent = document.pointerLockElement
    ? "Locked — move the mouse"
    : "Unlocked — click canvas to lock";
});

canvas.addEventListener("click", () => {
  canvas.requestPointerLock();
});

document.addEventListener("mousemove", (event) => {
  if (!document.pointerLockElement) return;
  yaw += event.movementX;
  pitch += event.movementY;
  out.textContent = `yaw: ${yaw}, pitch: ${pitch}`;
});

yaw: 42, pitch: -18

🚀 Common Use Cases

• FPS / third-person camera look controls.
• 3D model viewers that need continuous drag without leaving the viewport.
• Pausing a game loop when the user presses Esc to unlock.
• Updating “Click to play” overlays based on lock state.
• Pairing with fullscreen for immersive play modes.

🔧 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—listen on document.
• Check document.pointerLockElement for locked vs unlocked.
• Related learning: pointerLockElement, exitPointerLock(), requestPointerLock(), JavaScript hub.

💡 Best Practices