useDebounceCallback

Timing & async

A powerful React hook for debounced callbacks with cancel, flush, and pending methods

Install

$ npm install @usefy/use-debounce-callback

Quick start

useDebounceCallback.tsx

import { useDebounceCallback } from "@usefy/use-debounce-callback";

function SearchInput() {
  const [query, setQuery] = useState("");

  const debouncedSearch = useDebounceCallback((searchTerm: string) => {
    fetchSearchResults(searchTerm);
  }, 300);

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setQuery(e.target.value);
    debouncedSearch(e.target.value);
  };

  return (
    <input
      type="text"
      value={query}
      onChange={handleChange}
      placeholder="Search..."
    />
  );
}

API reference

`useDebounceCallback<T>(callback, delay?, options?)`

A hook that returns a debounced version of the provided callback function.

Parameters

Parameter	Type	Default	Description
`callback`	`T extends (...args: never[]) => unknown`	—	The callback function to debounce
`delay`	`number`	`500`	The debounce delay in milliseconds
`options`	`UseDebounceCallbackOptions`	`{}`	Additional configuration options

Options

Option	Type	Default	Description
`leading`	`boolean`	`false`	Invoke on the leading edge (first call)
`trailing`	`boolean`	`true`	Invoke on the trailing edge (after delay)
`maxWait`	`number`	—	Maximum time to wait before forcing invocation

Returns `DebouncedFunction<T>`

Property	Type	Description
`(...args)`	`ReturnType<T> \| undefined`	The debounced function (same parameters as the original). Returns the last callback result on a leading-edge invoke, otherwise `undefined`.
`cancel`	`() => void`	Cancels any pending invocation
`flush`	`() => ReturnType<T> \| undefined`	Immediately invokes any pending invocation and returns the last callback result (`undefined` if the callback has never run)
`pending`	`() => boolean`	Returns `true` if there's a pending invocation. Imperative check — see the caveat below; it does not trigger re-renders.

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →