React Frame Throttle 🚀

A lightweight, high-performance React hook designed to tame high-frequency data streams (like WebSockets, stock tickers, or mouse movements) by throttling updates to the browser's refresh rate (rAF).

Why use this? Standard throttle or debounce functions rely on setTimeout, which can drift and cause layout thrashing. react-frame-throttle decouples your data rate (e.g., 100 messages/sec) from your render rate (e.g., 60fps), ensuring your UI remains buttery smooth without dropping critical latest data.

Installation

npm install react-frame-throttle
# or
pnpm add react-frame-throttle
# or
yarn add react-frame-throttle

Usage

Basic Example (WebSocket / High Frequency Data)

import { useFrameThrottledState } from 'react-frame-throttle';

const StockTicker = ({ rawSocketPrice }) => {
  // rawSocketPrice might update 50 times a second.
  // displayedPrice will only update at 30 FPS (configurable).
  const displayedPrice = useFrameThrottledState(rawSocketPrice, { fps: 30 });

  return <div>{displayedPrice}</div>;
};

API

useFrameThrottledState<T>(value: T, options?: ThrottleOptions): T

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | value | T | - | The fast-changing value you want to throttle. | | options.fps | number | 60 | The target updates per second. | | options.paused | boolean | false | If true, stops updates (useful for "Freeze" buttons). |

Performance

This library uses requestAnimationFrame and useRef to avoid React reconciliation completely during the "throttled" frames. It has 0 overhead when the value isn't changing.

License

MIT