useDebounceSearch

Controls a search input with debouncing and a minimum character threshold. Only fires the onTimeOut callback after the user stops typing and the query meets the minimum length.

Signature

function useDebounceSearch(params: UseDebounceSearchParams): DebounceSearchController;

Params

type UseDebounceSearchParams = {
  onTimeOut: (query: string) => void;
  minQueryNumber?: number;
  initialQuery?: string | null;
  delay?: number;
};

Param	Type	Default	Description
`onTimeOut`	`(query: string) => void`	—	Called with the current query after `delay` ms of inactivity
`minQueryNumber`	`number`	`3`	Minimum characters required before `onTimeOut` is invoked
`initialQuery`	`string \| null`	`''`	Initial value of the controlled input
`delay`	`number`	`800`	Debounce delay in milliseconds

Returns

type DebounceSearchController = {
  query: string;
  handleChange: (value: string) => void;
};

Property	Type	Description
`query`	`string`	Current value of the search input
`handleChange`	`(value: string) => void`	Pass to the input's `onChange` handler

Usage

function SearchBox() {
  const { query, handleChange } = useDebounceSearch({
    onTimeOut: (q) => fetchResults(q),
    minQueryNumber: 2,
    delay: 500,
  });

  return <input value={query} onChange={(e) => handleChange(e.target.value)} placeholder="Search…" />;
}

Notes

Queries shorter than minQueryNumber (but not empty) cancel any pending debounced call.
Uses throttle-debounce under the hood via a stable useRef to avoid resetting the timer on each render.
Client-only ('use client').