JavaScript Document pointerLockElement Property

What You’ll Learn

Document.pointerLockElement is a read-only instance property that returns the Element receiving locked mouse events, or null. Learn MDN’s pointerlockchange pattern, how it parallels fullscreenElement, FPS game workflows, and five examples with try-it labs.

Introduction

Pointer lock lets web apps capture the mouse for first-person games, 3D viewers, and creative tools. While the pointer is locked, the browser hides the cursor and sends continuous movementX / movementY values. Scripts need to know which element owns that lock—that is what document.pointerLockElement provides.

MDN: the read-only property returns the Element set as the target for mouse events while the pointer is locked, or null if the lock is pending, the pointer is unlocked, or the target is in another document.

Related Document tutorials: fullscreenElement, activeElement, requestPointerLock(), Document constructor.

Understanding Document.pointerLockElement

A read-only instance property on Document. Its value is the element with an active pointer lock, or null when no lock applies to this document.

• Value — Element reference with lock, or null (MDN).
• Read-only — assigning does not throw; the setter is ignored (MDN no-op).
• Null cases — unlocked, lock pending, or locked element in another document (MDN).
• Typical element — often a <canvas> or game container after requestPointerLock().
• Exit — pair with document.exitPointerLock() when truthy, or Esc (MDN).

📝 Syntax

document.pointerLockElement

Value

An Element object — or null when pointer lock is not active for this document (MDN).

MDN example — sync Lock button on pointerlockchange

const lockButton = document.querySelector("#lock");
const container = document.querySelector("#container");

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

document.addEventListener("pointerlockchange", () => {
  if (document.pointerLockElement === container) {
    lockButton.disabled = true;
  } else {
    lockButton.disabled = false;
  }
});

Check if pointer lock is active

const isLocked = document.pointerLockElement !== null;
console.log("Pointer locked?", isLocked);

⚖️ Document Status Properties

Examples Gallery

Examples follow MDN Document: pointerLockElement. Try-it labs read the property safely; request pointer lock from a user click where the browser supports it.

console.log(document.pointerLockElement);
// null when pointer is not locked
console.log(document.pointerLockElement === null);

null
true

const lockButton = document.querySelector("#lock");
const container = document.querySelector("#container");

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

document.addEventListener("pointerlockchange", () => {
  lockButton.disabled = document.pointerLockElement === container;
});

Lock button disabled while container is locked.

const el = document.pointerLockElement;
if (el) {
  console.log(el.nodeName); // often "CANVAS" or "DIV"
  console.log(el.id);
} else {
  console.log("No locked element");
}

No locked element

function exitPointerLockSafe() {
  if (document.pointerLockElement) {
    document.exitPointerLock();
  }
}

exitPointerLockSafe(); // no-op when null

(no error — exit skipped when unlocked)

function updateLockUI() {
  const active = document.pointerLockElement !== null;
  console.log("Pointer locked?", active);
}

document.addEventListener("pointerlockchange", updateLockUI);
document.addEventListener("pointerlockerror", () => {
  console.log("Pointer lock request failed");
});

Pointer locked? true  (on lock)
Pointer locked? false (on unlock / Esc)

🚀 Common Use Cases

• FPS camera control — read movementX / movementY only when pointerLockElement matches your canvas.
• Toggle Lock button — disable while locked (MDN pattern).
• Custom unlock control — call exitPointerLock() when truthy.
• Game pause menu — exit lock when opening UI overlays.
• Debugging — log which element owns lock during development.
• Cross-mode checks — combine with fullscreenElement for immersive apps.

📝 Notes

• MDN: Limited availability (not Baseline) — no Deprecated / Experimental / Non-standard banner.
• Assigning to the property is a no-op; it never throws, even in strict mode (MDN).
• Returns null while a lock request is pending or when the locked element is in another document (MDN).
• Enter lock only from a user gesture; browsers block unsolicited lock requests.
• Related: requestPointerLock(), fullscreenElement, Document constructor.

💡 Best Practices