function useThrottler<TFn, TArgs>(fn, options): object
function useThrottler<TFn, TArgs>(fn, options): object
Defined in: react-pacer/src/throttler/useThrottler.ts:45
A low-level React hook that creates a Throttler instance that limits how often the provided function can execute.
This hook is designed to be flexible and state-management agnostic - it simply returns a throttler instance that you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc). For a simpler and higher-level hook that integrates directly with React's useState, see useThrottledState.
Throttling ensures a function executes at most once within a specified time window, regardless of how many times it is called. This is useful for rate-limiting expensive operations or UI updates.
The hook returns an object containing:
• TFn extends (...args) => any
• TArgs extends any[]
TFn
ThrottlerOptions
object
readonly cancel: () => void;
readonly cancel: () => void;
Cancels any pending trailing execution and clears internal state.
If a trailing execution is scheduled (due to throttling with trailing=true), this will prevent that execution from occurring. The internal timeout and stored arguments will be cleared.
Has no effect if there is no pending execution.
void
readonly getExecutionCount: () => number;
readonly getExecutionCount: () => number;
Returns the number of times the function has been executed
number
readonly maybeExecute: (...args) => void;
readonly maybeExecute: (...args) => void;
Attempts to execute the throttled function. The execution behavior depends on the throttler options:
If enough time has passed since the last execution (>= wait period):
If within the wait period:
...TArgs
void
const throttled = new Throttler(fn, { wait: 1000 });
// First call executes immediately
throttled.maybeExecute('a', 'b');
// Call during wait period - gets throttled
throttled.maybeExecute('c', 'd');
const throttled = new Throttler(fn, { wait: 1000 });
// First call executes immediately
throttled.maybeExecute('a', 'b');
// Call during wait period - gets throttled
throttled.maybeExecute('c', 'd');
// Basic throttling with custom state
const [value, setValue] = useState(0);
const { maybeExecute } = useThrottler(setValue, { wait: 1000 });
// With Redux
const dispatch = useDispatch();
const { maybeExecute } = useThrottler(
(value) => dispatch(updateAction(value)),
{ wait: 1000 }
);
// With any state manager
const { maybeExecute, cancel } = useThrottler(
(value) => stateManager.setState(value),
{
wait: 2000,
leading: true, // Execute immediately on first call
trailing: false // Skip trailing edge updates
}
);
// Basic throttling with custom state
const [value, setValue] = useState(0);
const { maybeExecute } = useThrottler(setValue, { wait: 1000 });
// With Redux
const dispatch = useDispatch();
const { maybeExecute } = useThrottler(
(value) => dispatch(updateAction(value)),
{ wait: 1000 }
);
// With any state manager
const { maybeExecute, cancel } = useThrottler(
(value) => stateManager.setState(value),
{
wait: 2000,
leading: true, // Execute immediately on first call
trailing: false // Skip trailing edge updates
}
);
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.