Pointer Lock API

Basic concepts

Pointer lock is related to pointer capture. Pointer capture provides continued delivery of events to a target element while a mouse is being dragged, but it stops when the mouse button is released. Pointer lock is different from pointer capture in the following ways:

• It is persistent: Pointer lock does not release the mouse until an explicit API call is made or the user uses a specific release gesture.
• It is not limited by browser or screen boundaries.
• It continues to send events regardless of mouse button state.
• It hides the cursor.

Method/properties overview

This section provides a brief description of each property and method related to the pointer lock specification.

requestPointerLock()

The Pointer lock API, similar to the Fullscreen API, extends DOM elements by adding a new method, requestPointerLock(). The following example requests pointer lock on a <canvas> element:

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

Operating systems enable mouse acceleration by default, which is useful when you sometimes want slow precise movement (think about you might use a graphics package), but also want to move great distances with a faster mouse movement (think about scrolling, and selecting several files). For some first-person perspective games however, raw mouse input data is preferred for controlling camera rotation — where the same distance movement, fast or slow, results in the same rotation. This results in a better gaming experience and higher accuracy, according to professional gamers.

To disable OS-level mouse acceleration and access raw mouse input, you can set the unadjustedMovement to true:

canvas.addEventListener("click", async () => {
  await canvas.requestPointerLock({
    unadjustedMovement: true,
  });
});

Handling promise and non-promise versions of requestPointerLock()

The above code snippet will still work in browsers that do not support the promise-based version of requestPointerLock() or the unadjustedMovement option — the await operator is permitted in front of a function that does not return a promise, and the options object will just be ignored in non-supporting browsers.

However, this could be confusing, and has other potential side-effects (for example, trying to use requestPointerLock().then() would throw an error in non-supporting browsers), so you may want to handle this explicitly using code along the following lines:

function requestPointerLockWithUnadjustedMovement() {
  const promise = myTargetElement.requestPointerLock({
    unadjustedMovement: true,
  });

  if (!promise) {
    console.log("disabling mouse acceleration is not supported");
    return;
  }

  return promise
    .then(() => console.log("pointer is locked"))
    .catch((error) => {
      if (error.name === "NotSupportedError") {
        // Some platforms may not support unadjusted movement.
        // You can request again a regular pointer lock.
        return myTargetElement.requestPointerLock();
      }
    });
}

pointerLockElement and exitPointerLock()

The Pointer lock API also extends the Document interface, adding a new property and a new method:

• pointerLockElement is used for accessing the currently locked element (if any).
• exitPointerLock() is used to exit the pointer lock.

The pointerLockElement property is useful for determining if any element is currently pointer locked (e.g., for doing a boolean check) and also for obtaining a reference to the locked element, if any.

Here is an example of using pointerLockElement:

if (document.pointerLockElement === canvas) {
  console.log("The pointer lock status is now locked");
} else {
  console.log("The pointer lock status is now unlocked");
}

The Document.exitPointerLock() method is used to exit pointer lock, and like requestPointerLock, works asynchronously using the pointerlockchange and pointerlockerror events, which you'll see more about below.

document.exitPointerLock();

pointerlockchange event

When the Pointer lock state changes—for example, when calling requestPointerLock() or exitPointerLock(), the user pressing the ESC key, etc.—the pointerlockchange event is dispatched to the document. This is a simple event containing no extra data.

document.addEventListener("pointerlockchange", lockChangeAlert);

function lockChangeAlert() {
  if (document.pointerLockElement === canvas) {
    console.log("The pointer lock status is now locked");
    // Do something useful in response
  } else {
    console.log("The pointer lock status is now unlocked");
    // Do something useful in response
  }
}

pointerlockerror event

When there is an error caused by calling requestPointerLock() or exitPointerLock(), the pointerlockerror event is dispatched to the document. This is a simple event containing no extra data.

document.addEventListener("pointerlockerror", lockError);

function lockError(e) {
  alert("Pointer lock failed");
}

Extensions to mouse events

The Pointer lock API extends the normal MouseEvent interface with movement attributes. Two new attributes to mouse events—movementX and movementY—provide the change in mouse positions. The values of the parameters are the same as the difference between the values of MouseEvent properties, screenX and screenY, which are stored in two subsequent mousemove events, eNow and ePrevious. In other words, the Pointer lock parameter movementX = eNow.screenX - ePrevious.screenX.

Locked state

When Pointer lock is enabled, the standard MouseEvent properties clientX, clientY, screenX, and screenY are held constant, as if the mouse is not moving. The movementX and movementY properties continue to provide the mouse's change in position. There is no limit to movementX and movementY values if the mouse is continuously moving in a single direction. The concept of the mouse cursor does not exist and the cursor cannot move off the window or be clamped by a screen edge.

Unlocked state

The parameters movementX and movementY are valid regardless of the mouse lock state, and are available even when unlocked for convenience.

When the mouse is unlocked, the system cursor can exit and re-enter the browser window. If that happens, movementX and movementY could be set to zero.

Simple example walkthrough

We've written a pointer lock demo (see source code) to show you how to use it to set up a simple control system. This demo uses JavaScript to draw a ball on top of a <canvas> element. When you click the canvas, pointer lock is then used to remove the mouse pointer and allow you to move the ball directly using the mouse. Let's see how this works.

We set initial x and y positions on the canvas:

let x = 50;
let y = 50;

Next we set up an event listener to run the requestPointerLock() method on the canvas when it is clicked, which initiates pointer lock. The document.pointerLockElement check is to see if there is already an active pointer lock — we don't want to keep calling requestPointerLock() on the canvas every time we click inside it if we already have pointer lock.

canvas.addEventListener("click", async () => {
  if (!document.pointerLockElement) {
    await canvas.requestPointerLock({
      unadjustedMovement: true,
    });
  }
});

Now for the dedicated pointer lock event listener: pointerlockchange. When this occurs, we run a function called lockChangeAlert() to handle the change.

document.addEventListener("pointerlockchange", lockChangeAlert);

This function checks the pointerLockElement property to see if it is our canvas. If so, it attached an event listener to handle the mouse movements with the updatePosition() function. If not, it removes the event listener again.

function lockChangeAlert() {
  if (document.pointerLockElement === canvas) {
    console.log("The pointer lock status is now locked");
    document.addEventListener("mousemove", updatePosition);
  } else {
    console.log("The pointer lock status is now unlocked");
    document.removeEventListener("mousemove", updatePosition);
  }
}

The updatePosition() function updates the position of the ball on the canvas (x and y), and also includes if () statements to check whether the ball has gone off the edges of the canvas. If so, it makes the ball wrap around to the opposite edge. It also includes a check whether a requestAnimationFrame() call has previously been made, and if so, calls it again as required, and calls the canvasDraw() function that updates the canvas scene. A tracker is also set up to write out the X and Y values to the screen, for reference.

const tracker = document.getElementById("tracker");

let animation;
function updatePosition(e) {
  x += e.movementX;
  y += e.movementY;
  if (x > canvas.width + RADIUS) {
    x = -RADIUS;
  }
  if (y > canvas.height + RADIUS) {
    y = -RADIUS;
  }
  if (x < -RADIUS) {
    x = canvas.width + RADIUS;
  }
  if (y < -RADIUS) {
    y = canvas.height + RADIUS;
  }
  tracker.textContent = `X position: ${x}, Y position: ${y}`;

  animation ??= requestAnimationFrame(() => {
    animation = null;
    canvasDraw();
  });
}

The canvasDraw() function draws the ball in the current x and y positions:

function canvasDraw() {
  ctx.fillStyle = "black";
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  ctx.fillStyle = "red";
  ctx.beginPath();
  ctx.arc(x, y, RADIUS, 0, degToRad(360), true);
  ctx.fill();
}

IFrame limitations

Pointer lock can only lock one <iframe> at a time. If you lock one <iframe>, you can't lock another one and transfer the target to it; pointer lock will error out. To avoid this limitation, first unlock the locked <iframe>, and then lock the other.

While <iframe> work by default, "sandboxed" <iframe>s block Pointer lock. To avoid this limitation, use <iframe sandbox="allow-pointer-lock">.

Specifications

Browser compatibility

api.Document.exitPointerLock

api.Element.requestPointerLock

See also

• MouseEvent
• Element.requestPointerLock()