usePointerLock

v0.0.14testeddemo

Reactive Pointer Lock API. Locks the mouse cursor to an element and tracks the locked element reactively.

Examples

const el = useTemplateRef<HTMLElement>('el');
const { lock, unlock, element } = usePointerLock(el);
// lock on user gesture
function onClick() { lock(el); }

// lock the element that received the event
const { lock } = usePointerLock();
function onDblClick(e: MouseEvent) { lock(e); }

Demo

Loading demo…

Signature

export function usePointerLock(
  target?: MaybeComputedElementRef,
  options: UsePointerLockOptions ={ ... }

Parameters

Parameter	Type	Default	Description
`target`?	`MaybeComputedElementRef`	—	Optional default element to lock when `lock` receives an `Event`
`options`?	`UsePointerLockOptions`	`{}`	Options

Returns

UsePointerLockReturn{ isSupported, element, triggerElement, lock, unlock }

Property	Type	Default	Description
`isSupported`	`ComputedRef<boolean>`	—	Whether the Pointer Lock API is supported (SSR-safe).
`element`	`ShallowRef<MaybeElement>`	—	The element that currently holds the pointer lock, or `null` when unlocked.
`triggerElement`	`ShallowRef<MaybeElement>`	—	The element whose event triggered the most recent `lock` call (the `event.currentTarget`), or `null` when locked programmatically / unlocked.
`lock`	`(eventOrTarget: MaybeComputedElementRef \| Event) => Promise<MaybeElement>`	—	Request pointer lock. Accepts either a DOM `Event` (locks its `currentTarget`, or the composable's `target` fallback) or an element ref. Resolves with the locked element once `pointerlockchange` confirms it.
`unlock`	`() => Promise<boolean>`	—	Release the pointer lock. Resolves `true` once released, `false` if it was not locked.