useThrottledCallback
Function: useThrottledCallback()
function useThrottledCallback<TFn, TSelected>(
fn,
options,
selector): (...args) => void
function useThrottledCallback<TFn, TSelected>(
fn,
options,
selector): (...args) => void
Defined in: react-pacer/src/throttler/useThrottledCallback.ts:61
A React hook that creates a throttled version of a callback function. This hook is essentially a wrapper around the basic throttle function that is exported from @tanstack/pacer, but optimized for React with reactive options and a stable function reference.
The throttled function will execute at most once within the specified wait time period, regardless of how many times it is called. If called multiple times during the wait period, only the first invocation will execute, and subsequent calls will be ignored until the wait period has elapsed.
This hook provides a simpler API compared to useThrottler, making it ideal for basic throttling needs. However, it does not expose the underlying Throttler instance.
State Management and Re-renders
By default, this callback hook disables re-renders from internal throttler state changes for optimal performance. The callback function reference remains stable regardless of internal state changes. However, you can opt into re-renders by providing a custom selector function that returns the specific state values you want to track.
For advanced usage requiring features like:
- Manual cancellation
- Access to execution counts
- Custom useCallback dependencies
Consider using the useThrottler hook instead.
Type Parameters
• TFn extends AnyFunction
• TSelected = {}
Parameters
fn
TFn
options
ThrottlerOptions<TFn>
selector
(state) => TSelected
Returns
Function
Parameters
args
...Parameters<TFn>
Returns
void
Example
// Throttle a window resize handler (no re-renders from internal state)
const handleResize = useThrottledCallback(() => {
updateLayoutMeasurements();
}, {
wait: 100 // Execute at most once every 100ms
});
// Opt into re-renders when execution count changes
const handleResize = useThrottledCallback(() => {
updateLayoutMeasurements();
},
{ wait: 100 },
(state) => ({ executionCount: state.executionCount })
);
// Use in an event listener
useEffect(() => {
window.addEventListener('resize', handleResize);
return () => window.removeEventListener('resize', handleResize);
}, [handleResize]);
// Throttle a window resize handler (no re-renders from internal state)
const handleResize = useThrottledCallback(() => {
updateLayoutMeasurements();
}, {
wait: 100 // Execute at most once every 100ms
});
// Opt into re-renders when execution count changes
const handleResize = useThrottledCallback(() => {
updateLayoutMeasurements();
},
{ wait: 100 },
(state) => ({ executionCount: state.executionCount })
);
// Use in an event listener
useEffect(() => {
window.addEventListener('resize', handleResize);
return () => window.removeEventListener('resize', handleResize);
}, [handleResize]);
Subscribe to Bytes
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.