Skip to main content

useDebouncedCallback

Returns a stable, debounced version of a callback, with cancel, flush and isPending controls and optional leading/trailing behavior. To debounce a value instead of a function call, use useDebouncedValue.

When to use it​

  • Searching or validating as the user types, with Enter to run immediately and Esc to cancel.
  • Autosaving drafts, saving right away on blur or unmount.
  • Ignoring rapid repeat actions such as double-clicks on a submit button.
  • Passing a debounced handler to dependency arrays or long-lived listeners without re-creating it.

Demo​

Edit the delay or the code below — the preview re-runs live. Open the Console tab to see when the callbacks run.

Loading demo…

Signature​

interface UseDebouncedCallbackOptions {
leading?: boolean;
trailing?: boolean;
flushOnUnmount?: boolean;
}

interface DebouncedFunction<T extends (...args: any[]) => void> {
(...args: Parameters<T>): void;
cancel: () => void;
flush: () => void;
isPending: () => boolean;
}

function useDebouncedCallback<T extends (...args: any[]) => void>(
callback: T,
delay: number,
options?: UseDebouncedCallbackOptions
): DebouncedFunction<T>;
ParameterTypeDescription
callbackTThe function to debounce.
delaynumberThe debounce delay, in milliseconds.
options.leadingbooleanInvoke immediately when a burst of calls starts. Defaults to false.
options.trailingbooleanInvoke with the latest arguments once calls pause. Defaults to true.
options.flushOnUnmountbooleanInvoke a pending call instead of discarding it on unmount. Default false.

Returns: a debounced function with the same parameters as callback, plus:

MemberDescription
cancel()Discards the pending call, if any.
flush()Invokes the pending call immediately with its latest arguments.
isPending()Returns true while a call is waiting to be invoked.

Usage notes​

  • Stable identity. The returned function (and its cancel, flush and isPending) never changes between renders, so it is safe in dependency arrays.
  • Always the latest callback. Changing callback or delay does not reset a running timer. The pending call runs the newest callback, and a new delay applies from the next call. The callback is read after each commit, so call the debounced function from handlers and effects rather than during render.
  • Leading and trailing. By default only the trailing call runs. With leading, the first call of a burst runs immediately; with both options, a trailing call follows only if there were further calls in the burst. With { leading: true, trailing: false } only the first call of each burst runs. Setting both to false means the callback never runs.
  • isPending is not reactive. It reads the current state and does not re-render your component when it changes. Use it in handlers, or pair it with state your callback already updates.
  • Unmount. A pending call is discarded and its timer cleared. Set flushOnUnmount to invoke it instead, for example to save a draft.
  • Return value. The callback's return value is ignored; the debounced function returns void.
  • Rate-limiting values. To limit how often a changing value updates, use useThrottledValue, or useDebouncedValue to wait for a pause.
  • Safe under React StrictMode.

Example​

const save = useDebouncedCallback(saveDraft, 1000, { flushOnUnmount: true });

return <textarea onChange={(e) => save(e.target.value)} onBlur={save.flush} />;

Hook source​

View useDebouncedCallback source

use-debounced-callback.ts
import { useEffect, useState } from "react";

import { useLatest } from "./use-latest";

/** Options for {@link useDebouncedCallback}. */
export interface UseDebouncedCallbackOptions {
/** Invoke the callback immediately when a burst of calls starts. Default is `false`. */
leading?: boolean;
/** Invoke the callback with the latest arguments once the calls pause. Default is `true`. */
trailing?: boolean;
/** Invoke any pending call (instead of discarding it) when the component unmounts. Default is `false`. */
flushOnUnmount?: boolean;
}

/**
* A debounced function returned by {@link useDebouncedCallback}, with controls
* to manage the pending call.
*
* @typeParam T - The type of the callback that was debounced.
*/
export interface DebouncedFunction<
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see `useDebouncedCallback`.
T extends (...args: any[]) => void,
> {
(...args: Parameters<T>): void;
/** Discard the pending call, if any. */
cancel: () => void;
/** Invoke the pending call immediately, if any. */
flush: () => void;
/** Whether a call is currently waiting to be invoked. */
isPending: () => boolean;
}

/**
* Returns a stable, debounced version of `callback` that is only invoked once
* `delay` milliseconds have passed since its last call, along with `cancel`,
* `flush` and `isPending` controls.
*
* The returned function keeps the same identity for the
* lifetime of the component and always invokes the latest `callback` and
* `delay`, so it is safe in dependency arrays and long-lived listeners. A new
* `delay` applies from the next call; a pending timer is not rescheduled.
*
* By default the callback runs on the trailing edge with the latest arguments.
* With `leading`, the first call of a burst runs immediately; with both
* `leading` and `trailing`, a trailing call only follows when there were
* further calls during the burst. With both set to `false` the callback is
* never invoked. The return value of `callback` is ignored. A pending call is
* discarded on unmount, or flushed when `flushOnUnmount` is set. For
* debouncing a value instead of a function call, see `useDebouncedValue`; for
* rate-limiting a continuously changing value, see `useThrottledValue`.
*
* @typeParam T - The type of the callback function to debounce.
* @param callback - The function to debounce.
* @param delay - The debounce delay in milliseconds.
* @param options - Optional {@link UseDebouncedCallbackOptions | leading/trailing and unmount} behavior.
* @returns A {@link DebouncedFunction | debounced function} with `cancel`, `flush` and `isPending`.
*
* @example
* ```tsx
* const search = useDebouncedCallback((query: string) => {
* fetchResults(query);
* }, 300);
*
* return <input onChange={(e) => search(e.target.value)} />;
* ```
*
* @example
* ```tsx
* // Autosave, flushing on blur and on unmount
* const save = useDebouncedCallback(saveDraft, 1000, { flushOnUnmount: true });
*
* return (
* <textarea onChange={(e) => save(e.target.value)} onBlur={save.flush} />
* );
* ```
*
* @example
* ```tsx
* // Ignore rapid repeat clicks, running only the first
* const submit = useDebouncedCallback(sendForm, 1000, {
* leading: true,
* trailing: false,
* });
* ```
*
* For a live, editable example, see the [useDebouncedCallback docs page](https://altalyst-solutions.github.io/hookify/hooks/use-debounced-callback).
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- `any[]` is required here (not `unknown[]`) so narrower callback signatures remain assignable to `T`, matching the pattern used by TS's own `Parameters<T>`.
export const useDebouncedCallback = <T extends (...args: any[]) => void>(
callback: T,
delay: number,
options?: UseDebouncedCallbackOptions
): DebouncedFunction<T> => {
const latest = useLatest({
callback,
delay,
leading: options?.leading ?? false,
trailing: options?.trailing ?? true,
flushOnUnmount: options?.flushOnUnmount ?? false,
});

const [debounced] = useState(() => {
let timer: ReturnType<typeof setTimeout> | null = null;
let pendingArgs: { args: Parameters<T> } | null = null;

const takePending = () => {
if (timer !== null) clearTimeout(timer);
timer = null;
const pending = pendingArgs;
pendingArgs = null;
return pending;
};

const fn = ((...args: Parameters<T>) => {
const { leading, trailing, delay } = latest.current;
const isIdle = timer === null;
if (timer !== null) clearTimeout(timer);

const runNow = isIdle && leading;
pendingArgs = !runNow && trailing ? { args } : null;
timer = setTimeout(() => {
const pending = takePending();
if (pending) latest.current.callback(...pending.args);
}, delay);

if (runNow) latest.current.callback(...args);
}) as DebouncedFunction<T>;

fn.cancel = () => {
takePending();
};
fn.flush = () => {
const pending = takePending();
if (pending) latest.current.callback(...pending.args);
};
fn.isPending = () => pendingArgs !== null;

return fn;
});

useEffect(
() => () => {
if (latest.current.flushOnUnmount) debounced.flush();
else debounced.cancel();
},
[debounced, latest]
);

return debounced;
};