Implementing useThrottle Custom Hook

Debounce simply resets a timer on each event. Throttle must actively track when the last execution happened and decide whether enough time has passed for another one. This requires persisting a timestamp between renders, making the implementation slightly more involved than debounce.

The last-execution timestamp must persist across renders without triggering re-renders itself, making useRef the right tool. Store the timestamp as const lastRunTime = useRef(Date.now()). Unlike state, updating a ref does not cause a re-render, so the throttle logic runs efficiently without extra cycles.

The useThrottle(value, delay) hook returns a throttled version of the input value. Its contract is similar to useDebounce: accept any value and a delay in ms, return the throttled value. Components use it the same way, making it a drop-in alternative for different timing semantics.

A trailing-edge throttle updates the value at the end of each interval. When a new value arrives, schedule a setTimeout for the remaining interval time: delay - (Date.now() - lastRunTime.current). When the timer fires, update the state and record the new lastRunTime. Cancel previous timers in cleanup.

A leading-edge throttle applies the first value immediately and ignores subsequent ones until the interval expires. Check: if Date.now() - lastRunTime.current >= delay, update state and record the time. Otherwise, skip the update. This provides instant feedback on first action with a cooldown period after.

The best UX often combines both: respond immediately to the first event (leading), then ensure the final state is also applied after the interval (trailing). This means the user sees a fast initial response and the final resting value is always applied after movement stops, preventing a stale end state.

Store the pending timeout ID in a useRef: const timeoutRef = useRef(null). Before scheduling a new timeout, call clearTimeout(timeoutRef.current) to cancel any existing one. This prevents multiple overlapping timers, which would cause multiple updates within a single throttle interval.

The useEffect cleanup should call clearTimeout(timeoutRef.current) to cancel any pending trailing update when the component unmounts. Without this, a pending timeout fires after unmount, attempting to set state on an unmounted component and potentially causing React warnings.

Instead of a value-based hook, you can create a useCallback-based throttle hook: useThrottledCallback(fn, delay) returns a throttled version of a function. This is more flexible when the operation you want to throttle is a function call (like an analytics tracker) rather than a reactive value.

In Jest tests, use jest.useFakeTimers() to control time. Set up a throttle with a 1000ms delay, fire 10 rapid value changes, then advance fake time by 500ms and check that only 1 or 2 updates happened. Advance by another 500ms and verify the trailing update fires. This validates throttle behavior deterministically.

React processes state updates in batches during renders. A throttle operating on state updates works within this model cleanly. However, note that in React 18 Concurrent Mode, renders can be interrupted. The throttle logic itself (based on real wall-clock time via Date.now()) is unaffected by React scheduling.

Which edge does a "trailing" throttle fire on?

Throttle requires tracking the last execution time with useRef. The hook can implement leading edge (immediate), trailing edge (deferred), or both. Always store the timeout ID in a ref and cancel it in cleanup. For function-based use cases, prefer a useThrottledCallback pattern. Test with fake timers for reliability.