pointer-lock

Error thrown when pointer lock cannot be acquired or released.


Package	`@vizejs/composable/pointer-lock`
Own the source	`vize lib pull composable:pointer-lock`
Runtime exports	`PointerLockError`, `usePointerLock`
Gzip budget	2816 B

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { PointerLockError, usePointerLock } from "@vizejs/composable/pointer-lock";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`usePointerLock`	input	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`document`	`resolveElement`, `tryOnScopeDispose`

API

`PointerLockError`

Error thrown when pointer lock cannot be acquired or released.

declare class PointerLockError extends Error {
    /** Machine-readable failure code. */
    readonly code: PointerLockErrorCode;
    /**
     * @param code Machine-readable failure code.
     * @param message Human-readable explanation.
     */
    constructor(code: PointerLockErrorCode, message: string);
}

`usePointerLock`

Reactive wrapper around the Pointer Lock API. Tracks pointerlockchange on the document and exposes promise-based lock and unlock actions that settle on the platform confirmation events. Rejections are PointerLockErrors with stable codes. Nothing runs during server rendering; listeners are removed with the owning scope. Inside a component the host is read after mounting, so hydration renders the server fallback first and never mismatches.

function usePointerLock( target?: MaybeElementTarget, options: UsePointerLockOptions = {}, ): PointerLockControls

Types

`PointerLockHost`

Document-like capability used by usePointerLock.

Member	Type	Description
`pointerLockElement`	`Element \| null`	Element that currently holds the pointer lock.
`exitPointerLock`	`() => void`	Release the pointer lock.

`UsePointerLockOptions`

Options for usePointerLock.

Member	Type	Description
`unadjustedMovement`?	`boolean`	Request raw (unaccelerated) movement deltas where supported.
`host`?	`MaybeRefOrGetter<PointerLockHost \| null \| undefined>`	Reactive document capability for alternate runtimes and tests.

`PointerLockControls`

Reactive state and actions returned by usePointerLock.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host supports pointer lock. `false` during server rendering.
`element`	`Readonly<ShallowRef<Element \| null>>`	Element currently holding the lock (any element, not only the target).
`isLocked`	`Readonly<Ref<boolean>>`	Whether the composable's own target holds the lock.
`lock`	`(target?: MaybeElementTarget) => Promise<Element>`	Lock the pointer to `target` (or the composable target).
`unlock`	`() => Promise<boolean>`	Release the lock.