useAnimationFrame

useAnimationFrame(fn) drives fn(timestamp) once per animation frame. It returns { start, stop }, does not start automatically, and auto-stops on scope dispose. fn may call stop() (or start()) to break out of or restart the loop synchronously — the next frame is scheduled before fn runs, so a cancel inside takes effect immediately. Part of pota/use/animate.

Arguments

Argument	Type	Description
fn	(timestamp: DOMHighResTimeStamp) => void	Called once per frame with the frame's clock

Returns: { start, stop } — both methods return the controller so calls can be chained. start() restarts the loop; stop() cancels the pending frame.

Examples

A frame counter

Counts elapsed frames into a signal and stops the loop after one hundred. Calling stop() from inside fn cancels the already-scheduled next frame, so the loop halts on the same tick.

import { render, signal } from 'pota'
import { useAnimationFrame } from 'pota/use/animate'

function App() {
	const frames = signal(0)

	const loop = useAnimationFrame(() => {
		frames.update(n => n + 1)
		if (frames.read() >= 100) loop.stop()
	})

	return (
		<>
			<button on:click={() => loop.start()}>start</button>
			<button on:click={() => loop.stop()}>stop</button>
			<p>frames: {frames.read}</p>
		</>
	)
}

render(App)