useThrottle

Hook to limit function execution frequency.

Demo

INFO

The component has:

• A state internal with 0 value.
• A useThrottle hook that receives an async function that increments state variable after 3 seconds and waitFn true as option. It returns the debounced function fn, the function to cancel throttle limitation cancel and the function immediate to immediately execute function. Each function is executed by onClick event of three button elements.

Loading demo…

Show source code

import { useCallback, useState } from "react"
import { useThrottle } from "../../../..";

export const UseThrottle = () => {
	const [state, setState] = useState(0);
	const [fn, cancel, immediate] = useThrottle(
		useCallback(() => new Promise(res => setTimeout(() => res(setState(t => t + 1)), 3000)), []),
		{
			waitFn: true
		}
	);


	return (<div>
		<p>State is: {state}</p>
		<div style={{ display: "grid", gridTemplateColumns: "auto auto auto", justifyContent: "center", gap: 50 }}>
			<button onClick={fn}>Throttled increment</button>
			<button onClick={immediate}>Immediatly increment</button>
			<button onClick={cancel}>Cancel</button>
		</div>
	</div>);
}

Types

UseThrottleOptions

Options that control the throttle behaviour of useThrottle. Exactly one of delay or waitFn should be set.

Property	Type	Required	Description
delay	number		Minimum number of milliseconds that must elapse between successive invocations of fn. After fn is called, further calls are dropped until the delay has expired. A value of 0 allows back-to-back calls on consecutive ticks. Mutually exclusive with waitFn.
waitFn	boolean		When true, throttling is based on the completion of fn rather than a fixed time interval. The next invocation is only allowed once the Promise returned by the previous call has settled. If fn returns void (i.e. is synchronous), the lock is released immediately after the call returns. Mutually exclusive with delay.

UseThrottleProps

• @template T - The argument tuple type of the function to throttle. Inferred automatically from the fn argument.

Parameters accepted by useThrottle.

Property	Type	Required	Description
fn	(...args: T) => void \| Promise<void>	✓	The function to throttle. Accepts any number of arguments and may return either void or a Promise&lt;void&gt;. The same argument types are preserved on the returned throttled function.
opts	UseThrottleOptions	✓	Configuration that controls the throttle strategy. Exactly one of delay or waitFn must be provided — supplying neither will cause the throttled function to throw at call time.

UseThrottleResult

• @template T - The argument tuple type of the throttled function.

Return value of {@link https://ndriadev.github.io/react-tools/hooks/api-dom/useThrottle}.

Index	Type	Description
[0]	(...args: T) => void	The throttled version of fn. Calls are forwarded to fn only when the throttle condition is not active; otherwise they are silently dropped. Preserves the original argument signature of fn.
[1]	() => void	Resets the throttle state immediately, allowing the next call to fn to pass through regardless of whether the delay has elapsed or the previous Promise has settled.
[2]	(...args: T) => void	Bypasses throttling entirely and invokes fn immediately with the provided arguments, also resetting the throttle state so the next throttled call is treated as a fresh invocation.