W3cubDocs

/Web APIs

Element: requestPointerLock() method

The Element.requestPointerLock() method lets you asynchronously ask for the pointer to be locked on the given element.

To track the success or failure of the request, it is necessary to listen for the pointerlockchange and pointerlockerror events at the Document level.

Syntax

js

requestPointerLock()
requestPointerLock(options)

Parameters

options Optional

An options object that can contain the following properties:

unadjustedMovement Optional

Disables OS-level adjustment for mouse acceleration, and accesses raw mouse input instead. The default value is false; setting it to true will disable mouse acceleration.

Return value

A Promise that resolves with undefined.

Note: Some browsers do not yet support the promise version of requestPointerLock(), just the older synchronous version.

Examples

Pointer lock is often used in online games, when you want your mouse movement to be focused on controlling the game, without the distraction of the mouse pointer moving around, going outside the game area, or reaching the edge of the window.

To enable pointer lock, you would get the user to interact with the UI in some way, perhaps by pressing a button, or the game canvas itself.

js

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:

js

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

For more example code, see:

Security

Transient user activation is required. The user has to interact with the page or a UI element in order for this feature to work.

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
requestPointerLock
37From version 92, returns a promise instead of undefined. The behavior reflects a proposed specification change.
22–38
13From version 92, returns a promise instead of undefined. The behavior reflects a proposed specification change.
5014–50 No
24From version 78, returns a promise instead of undefined. The behavior reflects a proposed specification change.
15–25
10.1
37From version 92, returns a promise instead of undefined. The behavior reflects a proposed specification change.
4.4–38
37From version 92, returns a promise instead of undefined. The behavior reflects a proposed specification change.
25–38
5014–50
24From version 65, returns a promise instead of undefined. The behavior reflects a proposed specification change.
14–25
No
3.0From version 16, returns a promise instead of undefined. The behavior reflects a proposed specification change.
1.5–3.0
options_unadjustedMovement_parameter
88Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.
88Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.
No No
74Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.
No
88Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.
88Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.
No
63Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.
No
15.0Supported on macOS Catalina 10.15.1+, Windows, and ChromeOS. Not yet supported on Linux.

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Element/requestPointerLock