Implementing useDebounce Custom Hook

The useDebounce hook accepts a value and a delay in milliseconds, and returns a debounced version of that value: function useDebounce(value, delay). The returned debouncedValue lags behind the real value, updating only after the specified delay has elapsed without another change.

Inside the hook, declare a state variable: const [debouncedValue, setDebouncedValue] = useState(value). This state holds the last committed value. It starts equal to the initial value and only updates after the debounce timer fires. Components that read debouncedValue see a stable, settled input.

The core logic lives in a useEffect: create a timer with setTimeout(() => setDebouncedValue(value), delay) and store the ID. The effect runs every time value or delay changes. The timer fires delay milliseconds after the last change, updating the debounced state.

The useEffect cleanup function calls clearTimeout(timerId). When value changes before the timer fires, React runs the cleanup, cancelling the pending update. A new timer is then scheduled. This is the key mechanism that makes debouncing work: rapid changes keep resetting the timer.

The useEffect dependency array should contain [value, delay]. The effect re-runs whenever the input value changes (so a new timer is scheduled) and whenever delay changes (in case the caller adjusts the debounce interval dynamically). Both must be included to avoid stale closure issues.

Usage is straightforward: const debouncedSearch = useDebounce(searchInput, 300). A separate useEffect with [debouncedSearch] as its dependency fires the API call. The input state (searchInput) updates immediately keeping the input responsive; only the API call waits for the debounce.

By default, the standard implementation only runs on the trailing edge. For an "immediate" mode that calls the function on the first trigger but debounces subsequent calls, you need a ref to track whether the call has been made and reset it after the timeout. This is more complex but useful for submit buttons.

Make the hook generic for type safety: function useDebounce(value: T, delay: number): T. This allows TypeScript to infer the type of debouncedValue from the type of value. The generic parameter T propagates through the internal state and the return type automatically.

A frequent mistake is forgetting to return the cleanup function from the useEffect. Without cleanup, every value change creates a new timer but never cancels the old one. The result is that multiple timers fire, causing setDebouncedValue to be called multiple times with stale values, defeating the debounce entirely.

An alternative is to store the debounce function itself in a useRef using lodash. Unlike the state-based approach, the ref approach debounces callbacks (functions) rather than values. Use the state-based hook when you need a derived value; use the callback approach when you need to debounce an event handler.

Verify your hook works by adding a console log inside the timeout callback and watching the browser console while typing rapidly. You should see one log per "stop" event, not one per keystroke. The number of logs should be much less than the number of keystrokes during fast typing.

Why does the useEffect in useDebounce need to return a cleanup function that calls clearTimeout?

The useDebounce(value, delay) hook holds a debounced state updated only after delay ms of silence. Its useEffect sets a timeout and clears it on cleanup to cancel stale timers. Use the debounced value as a dependency for API-fetching effects. Add a TypeScript generic for full type safety.