use-raf-fn

Run a callback on every animation frame, with pause/resume controls and an optional frame-rate cap.

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 { useRafFn } from "@vizejs/composable/use-raf-fn";

Try it

Animate a progress bar

Run code on every animation frame with the time since the previous frame.

Open the interactive example

What to observe: Start fills the bar over about two seconds; Pause stops it and Reset empties it.

delta is in milliseconds, so the speed does not depend on the frame rate. Pass fpsLimit to throttle frames.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useRafFn } from "@vizejs/composable/use-raf-fn";

const progress = ref(0);
const { isActive, pause, resume } = useRafFn(
  ({ delta }) => {
    progress.value = Math.min(100, progress.value + delta / 20);
    if (progress.value >= 100) pause();
  },
  { immediate: false },
);
</script>

<template>
  <div class="composable-example">
    <p>Animate a progress bar frame by frame, independent of the frame rate.</p>
    <progress :value="progress" max="100" aria-label="Upload progress"></progress>
    <div class="example-actions">
      <button type="button" :disabled="isActive || progress >= 100" @click="() => resume()">
        Start
      </button>
      <button type="button" :disabled="!isActive" @click="() => pause()">Pause</button>
      <button type="button" @click="() => (progress = 0)">Reset</button>
    </div>
    <output aria-live="off">{{ Math.round(progress) }}%</output>
  </div>
</template>

Runtime contract

API

useRafFn

Run a callback on every animation frame, with pause/resume controls and an optional frame-rate cap. The host is resolved lazily on resume(), so importing and calling this during server rendering is safe: without a browser window (and without UseRafFnOptions.runOnServer), or without any frame host, isActive reports the requested state and no callbacks run, matching the client's initial render. The pending frame is cancelled when the owning reactive scope stops.

function useRafFn( callback: (frame: RafFrame) => void, options: UseRafFnOptions = {}, ): PausableControls

const { pause } = useRafFn(({ delta }) => step(delta), { fpsLimit: 30 });

Types

FrameScheduler

Animation-frame host used by useRafFn. Implement this interface to drive frames from a deterministic test clock, a native display link, or an offscreen renderer.

RafFrame

Timing information passed to every useRafFn callback.

UseRafFnOptions

Options for useRafFn.