⬅️ Back to Table of Contents

📄 usePointerLock

📊 Analysis Summary

Metric	Count
🔧 Functions	3
📦 Imports	11
⚡ Async/Await Patterns	3
📐 Interfaces	2

📚 Table of Contents

• Imports
• Async/Await Patterns
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/usePointerLock/index.ts

📦 Imports

Name	Source
ShallowRef	vue
ConfigurableDocument	../_configurable
Supportable	../types
MaybeElement	../unrefElement
MaybeElementRef	../unrefElement
until	@vueuse/shared
shallowRef	vue
defaultDocument	../_configurable
unrefElement	../unrefElement
useEventListener	../useEventListener
useSupported	../useSupported

---

Async/Await Patterns

Type	Function	Await Expressions	Promise Chains
await-expression	usePointerLock	until(element).toBe(targetElement), until(element).toBeNull()	none
async-function	lock	until(element).toBe(targetElement)	none
async-function	unlock	until(element).toBeNull()	none

---

Functions

usePointerLock(target: MaybeElementRef, options: UsePointerLockOptions): UsePointerLockReturn

Reactive pointer lock.

Parameters:

• target any: No description
• options any: No description

See: https://vueuse.org/usePointerLock

Tags: @__NO_SIDE_EFFECTS__

Raw JSDoc

/**
 * Reactive pointer lock.
 *
 * @see https://vueuse.org/usePointerLock
 * @param target
 * @param options
 *
 * @__NO_SIDE_EFFECTS__
 */

Calls:

• useSupported (from ../useSupported)
• shallowRef (from vue)
• useEventListener (from ../useEventListener)
• unrefElement (from ../unrefElement)
• targetElement.requestPointerLock
• until(element).toBe
• document!.exitPointerLock
• until(element).toBeNull

Code

export function usePointerLock(target?: MaybeElementRef, options: UsePointerLockOptions = {}): UsePointerLockReturn {
  const { document = defaultDocument } = options

  const isSupported = useSupported(() => document && 'pointerLockElement' in document)

  const element = shallowRef<MaybeElement>()

  const triggerElement = shallowRef<MaybeElement>()

  let targetElement: MaybeElement

  if (isSupported.value) {
    const listenerOptions = { passive: true }

    useEventListener(document, 'pointerlockchange', () => {
      const currentElement = document!.pointerLockElement ?? element.value
      if (targetElement && currentElement === targetElement) {
        element.value = document!.pointerLockElement as MaybeElement
        if (!element.value)
          targetElement = triggerElement.value = null
      }
    }, listenerOptions)

    useEventListener(document, 'pointerlockerror', () => {
      const currentElement = document!.pointerLockElement ?? element.value
      if (targetElement && currentElement === targetElement) {
        const action = document!.pointerLockElement ? 'release' : 'acquire'
        throw new Error(`Failed to ${action} pointer lock.`)
      }
    }, listenerOptions)
  }

  async function lock(
    e: MaybeElementRef | Event,
    // options?: PointerLockOptions,
  ) {
    if (!isSupported.value)
      throw new Error('Pointer Lock API is not supported by your browser.')

    triggerElement.value = e instanceof Event ? <HTMLElement>e.currentTarget : null
    targetElement = e instanceof Event ? unrefElement(target) ?? triggerElement.value : unrefElement(e)
    if (!targetElement)
      throw new Error('Target element undefined.')
    targetElement.requestPointerLock()

    return await until(element).toBe(targetElement)
  }

  async function unlock() {
    if (!element.value)
      return false

    document!.exitPointerLock()

    await until(element).toBeNull()
    return true
  }

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

Internal helpers

Declared inside another function in this file.

lock(e: MaybeElementRef | Event): Promise<any>

Parameters:

• e MaybeElementRef | Event

Returns: Promise<any>

Calls:

• unrefElement (from ../unrefElement)
• targetElement.requestPointerLock
• until(element).toBe

Code

async function lock(
    e: MaybeElementRef | Event,
    // options?: PointerLockOptions,
  ) {
    if (!isSupported.value)
      throw new Error('Pointer Lock API is not supported by your browser.')

    triggerElement.value = e instanceof Event ? <HTMLElement>e.currentTarget : null
    targetElement = e instanceof Event ? unrefElement(target) ?? triggerElement.value : unrefElement(e)
    if (!targetElement)
      throw new Error('Target element undefined.')
    targetElement.requestPointerLock()

    return await until(element).toBe(targetElement)
  }

unlock(): Promise<boolean>

Returns: Promise<boolean>

Calls:

• document!.exitPointerLock
• until(element).toBeNull

Code

async function unlock() {
    if (!element.value)
      return false

    document!.exitPointerLock()

    await until(element).toBeNull()
    return true
  }

---

Interfaces

UsePointerLockOptions

Interface Code

export interface UsePointerLockOptions extends ConfigurableDocument {
  // pointerLockOptions?: PointerLockOptions
}

UsePointerLockReturn

Interface Code

export interface UsePointerLockReturn extends Supportable {
  element: ShallowRef<MaybeElement>
  triggerElement: ShallowRef<MaybeElement>
  lock: (e: MaybeElementRef | Event) => Promise<MaybeElement>
  unlock: () => Promise<boolean>
}

Properties

Name	Type	Optional	Description
element	ShallowRef<MaybeElement>	✗	not shown
triggerElement	ShallowRef<MaybeElement>	✗	not shown
lock	(e: MaybeElementRef \| Event) => Promise<MaybeElement>	✗	not shown
unlock	() => Promise<boolean>	✗	not shown

---

Generated by Syntax Scribe