useThrottle
Executes a callback immediately at most once per timeout window.
About
useThrottle provides a leading-edge throttle. The first call runs immediately, the gate closes synchronously, and calls made before the timeout ends are dropped rather than queued.
Examples
import { useState } from "react";
import { useThrottle } from "rooks";
export default function ThrottledCounter() {
const [count, setCount] = useState(0);
const [increment, isReady] = useThrottle(
() => setCount((value) => value + 1),
500
);
return (
<section>
<p>Count: {count}</p>
<button type="button" onClick={() => increment()} disabled={!isReady}>
{isReady ? "Increment" : "Cooling down"}
</button>
</section>
);
}Parameters
| Argument | Type | Default | Meaning |
|---|---|---|---|
callback | (...args: T[]) => void | required | Latest callback to invoke. |
timeout | number | 300 | Cooldown duration in milliseconds. |
Return value
[throttledFunction, isReady]. The function is stable and forwards arguments. isReady is true when a call will execute.
Behavior and lifecycle
The gate closes through a ref before the callback runs, so several synchronous calls still invoke once. A timeout reopens the gate; no trailing call is saved. Changing timeout while closed clears the old timer and starts a full new timeout. Unmount clears the timer. Callback errors propagate, but the gate has already closed.
Compatibility and accessibility
The cooldown timer uses window from an effect, so server rendering schedules nothing. If readiness disables a control, the changed label should remain clear and the timeout should not trap users who need more time to complete an action.