⬅️ Back to Table of Contents

📄 useRafFn

📊 Analysis Summary

Metric	Count
🔧 Functions	4
📦 Imports	9
🟢 Vue Composition API	1
📐 Interfaces	2

📚 Table of Contents

• Imports
• Vue Composition API
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useRafFn/index.ts

📦 Imports

Name	Source
Pausable	@vueuse/shared
MaybeRefOrGetter	vue
ConfigurableWindow	../_configurable
tryOnScopeDispose	@vueuse/shared
computed	vue
shallowReadonly	vue
shallowRef	vue
toValue	vue
defaultWindow	../_configurable

---

Vue Composition API

Name	Type	Reactive Variables	Composables
computed	computed	none	none

---

Functions

useRafFn(fn: (args: UseRafFnCallbackArguments) => vo…, options: UseRafFnOptions): Pausable

Call function on every requestAnimationFrame. With controls of pausing and resuming.

Parameters:

• fn any: No description
• options any: No description

See: https://vueuse.org/useRafFn

Raw JSDoc

/**
 * Call function on every `requestAnimationFrame`. With controls of pausing and resuming.
 *
 * @see https://vueuse.org/useRafFn
 * @param fn
 * @param options
 */

Calls:

• shallowRef (from vue)
• computed (from vue)
• toValue (from vue)
• window.requestAnimationFrame
• fn
• window.cancelAnimationFrame
• resume
• tryOnScopeDispose (from @vueuse/shared)
• shallowReadonly (from vue)

Code

export function useRafFn(fn: (args: UseRafFnCallbackArguments) => void, options: UseRafFnOptions = {}): Pausable {
  const {
    immediate = true,
    fpsLimit = null,
    window = defaultWindow,
    once = false,
  } = options

  const isActive = shallowRef(false)
  const intervalLimit = computed(() => {
    const limit = toValue(fpsLimit)
    return limit ? 1000 / limit : null
  })
  let previousFrameTimestamp = 0
  let rafId: null | number = null

  function loop(timestamp: DOMHighResTimeStamp) {
    if (!isActive.value || !window)
      return

    if (!previousFrameTimestamp)
      previousFrameTimestamp = timestamp

    const delta = timestamp - previousFrameTimestamp

    if (intervalLimit.value && delta < intervalLimit.value) {
      rafId = window.requestAnimationFrame(loop)
      return
    }

    previousFrameTimestamp = timestamp
    fn({ delta, timestamp })
    if (once) {
      isActive.value = false
      rafId = null
      return
    }
    rafId = window.requestAnimationFrame(loop)
  }

  function resume() {
    if (!isActive.value && window) {
      isActive.value = true
      previousFrameTimestamp = 0
      rafId = window.requestAnimationFrame(loop)
    }
  }

  function pause() {
    isActive.value = false
    if (rafId != null && window) {
      window.cancelAnimationFrame(rafId)
      rafId = null
    }
  }

  if (immediate)
    resume()

  tryOnScopeDispose(pause)

  return {
    isActive: shallowReadonly(isActive),
    pause,
    resume,
  }
}

Internal helpers

Declared inside another function in this file.

loop(timestamp: DOMHighResTimeStamp): void

Parameters:

• timestamp DOMHighResTimeStamp

Returns: void

Calls:

• window.requestAnimationFrame
• fn

Code

function loop(timestamp: DOMHighResTimeStamp) {
    if (!isActive.value || !window)
      return

    if (!previousFrameTimestamp)
      previousFrameTimestamp = timestamp

    const delta = timestamp - previousFrameTimestamp

    if (intervalLimit.value && delta < intervalLimit.value) {
      rafId = window.requestAnimationFrame(loop)
      return
    }

    previousFrameTimestamp = timestamp
    fn({ delta, timestamp })
    if (once) {
      isActive.value = false
      rafId = null
      return
    }
    rafId = window.requestAnimationFrame(loop)
  }

resume(): void

Returns: void

Calls:

• window.requestAnimationFrame

Code

function resume() {
    if (!isActive.value && window) {
      isActive.value = true
      previousFrameTimestamp = 0
      rafId = window.requestAnimationFrame(loop)
    }
  }

pause(): void

Returns: void

Calls:

• window.cancelAnimationFrame

Code

function pause() {
    isActive.value = false
    if (rafId != null && window) {
      window.cancelAnimationFrame(rafId)
      rafId = null
    }
  }

---

Interfaces

UseRafFnCallbackArguments

Interface Code

export interface UseRafFnCallbackArguments {
  /**
   * Time elapsed between this and the last frame.
   */
  delta: number

  /**
   * Time elapsed since the creation of the web page. See {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp#the_time_origin Time origin}.
   */
  timestamp: DOMHighResTimeStamp
}

Properties

Name	Type	Optional	Description
delta	number	✗	not shown
timestamp	DOMHighResTimeStamp	✗	not shown

UseRafFnOptions

Interface Code

export interface UseRafFnOptions extends ConfigurableWindow {
  /**
   * Start the requestAnimationFrame loop immediately on creation
   *
   * @default true
   */
  immediate?: boolean
  /**
   * The maximum frame per second to execute the function.
   * Set to `null` to disable the limit.
   *
   * @default null
   */
  fpsLimit?: MaybeRefOrGetter<number | null>
  /**
   * After the requestAnimationFrame loop executed once, it will be automatically stopped.
   *
   * @default false
   */
  once?: boolean
}

Properties

Name	Type	Optional	Description
immediate	boolean	✓	not shown
fpsLimit	MaybeRefOrGetter<number \| null>	✓	not shown
once	boolean	✓	not shown

---

Generated by Syntax Scribe