admin/packages/hooks/src/useDebounceSearch/Readme.md

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').