useDebounceFn
Overview
useDebounceFn schedules the latest arguments after a quiet period and exposes explicit lifecycle controls.
Signature
function useDebounceFn<Args extends unknown[], Result>(
fn: (...args: Args) => Result,
options: DebounceFnOptions,
): {
run: (...args: Args) => void;
cancel: () => void;
flush: () => Result | undefined;
pending: boolean;
};Parameters
fn is read from the latest commit. Options use required delay, optional leading, trailing, finite maxWait, and an onError observer.
Returns
run queues arguments, cancel drops them, flush invokes them immediately, and pending reports queued work.
Behavior
Defaults are trailing-only. flush clears both timers and returns the callback result; unmount clears pending work without invoking it. If the callback throws, pending arguments and timers are cleared before onError runs and the original error is rethrown.
SSR / RSC
Render creates no timer. Calling run is an interaction-time operation; use the Hook in a Client Component.
Example
Composition
Call flush before navigation when a queued local save must finish synchronously.