useRafFn

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

Frames: 0

Delta: 0ms

Resume

Usage

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

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

FPS limit

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

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

Run once

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

useRafFn(
  ({ 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):

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

// ✅ 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 Declarations

export interface UseRafFnCallbackArguments {
    delta: number;
    timestamp: DOMHighResTimeStamp;
}
export interface UseRafFnOptions {
    immediate?: boolean;
    fpsLimit?: MaybeObservable<number | null>;
    once?: boolean;
}
export declare function useRafFn(fn: (args: UseRafFnCallbackArguments) => void, options?: UseRafFnOptions): Pausable;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)