useRafFn

Call a function on every requestAnimationFrame with pause/resume control

Execute a function on every animation frame (requestAnimationFrame) with reactive isActive state and pause/resume control. The callback receives delta (ms since last frame) and timestamp (ms since page load).

Demo

requestAnimationFrame

Paused

Tracks frame count and delta time.

Frames

0

Delta

0ms

Resume

Usage

Hook

import { useRafFn } from "@usels/web";

function Component() {
  const { isActive, pause, resume } = useRafFn(({ delta, timestamp }) => {
    // called ~60 times/sec
    console.log(`delta: ${delta}ms`);
  });
}

Scope

import { createRafFn } from "@usels/web";

function Component() {
  "use scope"
  const { isActive$, pause, resume } = createRafFn(({ delta, timestamp }) => {
    // called ~60 times/sec
    console.log(`delta: ${delta}ms`);
  });
}

FPS limit

Hook

import { observable, useRafFn } from "@usels/web";

function Component() {
  const fps$ = observable(30);
  useRafFn(({ delta }) => {}, { fpsLimit: fps$ });
  // caps execution to 30fps; fps$.set(60) applies next frame
}

Scope

import { createRafFn, observable } from "@usels/web";

function Component() {
  "use scope"
  const fps$ = observable(30);
  createRafFn(({ delta }) => {}, { fpsLimit: fps$ });
  // caps execution to 30fps; fps$.set(60) applies next frame
}

Run once

Hook

import { useRafFn } from "@usels/web";

function Component() {
  useRafFn(
    ({ timestamp }) => {
      console.log("ran once at", timestamp);
    },
    { once: true }
  );
}

Scope

import { createRafFn } from "@usels/web";

function Component() {
  "use scope"
  createRafFn(
    ({ timestamp }) => {
      console.log("ran once at", timestamp);
    },
    { once: true }
  );
}

Note: once: true means “pause after the first frame per resume cycle”. Calling resume() again starts a new cycle.

Notes

delta on the first frame

delta is always 0 on the first frame after resume(). This avoids a production pitfall where the DOMHighResTimeStamp accumulates from page load (potentially thousands of ms), causing physics simulations to jump on the first frame.

fpsLimit valid values

Only positive finite numbers limit the frame rate. All other values behave as unlimited:

fpsLimit	Behavior
null (default)	Unlimited
60	Capped at 60 fps
0	Unlimited (not “stopped”)
NaN	Unlimited
Infinity	Unlimited
negative	Unlimited

To stop the loop, use pause() instead of setting fpsLimit to a non-positive value.

Reactive fpsLimit

Pass an Observable when you need to change the fps cap at runtime. A plain number is captured at mount time and will not update if the component re-renders with a new value (stale closure):

// @noErrors
import { observable, useRafFn } from "@usels/web";

// ✅ Reactive — changes apply on the next frame
const fps$ = observable(30);
useRafFn(fn, { fpsLimit: fps$ });
fps$.set(60); // takes effect immediately

// ❌ Stale closure — re-render with a new number has no effect
const [fps, setFps] = useState(30);
useRafFn(fn, { fpsLimit: fps }); // captures 30 at mount, never updates

Type

Parameters

Parameter	Type	Description
fn	(args: RafFnCallbackArguments) => void	-
options	RafFnOptions | undefined (optional)	-

RafFnOptions

Option	Type	Default	Description
immediate	boolean	true	If true, starts immediately on creation.
fpsLimit	MaybeObservable<number | null>	null	Cap execution to this many frames per second. null = unlimited.
once	boolean	false	If true, pauses after the first frame executes.

Returns

Pausable

Name	Type	Description
isActive$	ReadonlyObservable<boolean>	-
pause	Fn	-
resume	Fn	-

Source

View on GitHub