React useDebounce Hook: Debounce State & Callbacks (2026)

You have a search box. The user types react hooks, and your component fires an API request on every single keystroke — eleven requests for one query, ten of them already stale by the time they resolve. The fix everyone reaches for is debouncing: wait until the typing stops, then fire once. The fix everyone gets wrong is writing that debounce by hand with setTimeout inside a component, where stale closures, missing cleanup, and re-render churn quietly break it.

useDebounce is the hook that gets it right. This post covers the two shapes you actually need — debouncing a value and debouncing a callback — when to use each, and how to cancel or flush pending calls. Everything here is the real .) The hard part is doing it inside a React component. Here is the naive version, and it has three bugs:

function Search() {

  const [query, setQuery] = useState('');

  const timer = useRef<ReturnType<typeof setTimeout>>();



  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {

    const value = e.target.value;

    setQuery(value);

    clearTimeout(timer.current);

    timer.current = setTimeout(() => {

      fetchResults(value); // 🐛 see below

    }, 300);

  }



  return <input value={query} onChange={handleChange} />;

}

1. 
   It leaks on unmount. If the component unmounts while a timer is pending, the callback still fires 300 ms later — often setting state on a gone component, or hitting an API for a screen the user already left.


2. 
   It captures stale values. The moment you debounce anything other than the raw event value — a second piece of state, a prop, a derived value — the closure freezes whatever those were when the timer was set, not when it fires.


3. 
   It spreads. Every place that needs debouncing re-implements the useRef + clearTimeout dance, and each copy is a chance to forget the cleanup.

A hook fixes all three in one place. ReactUse ships two, built on the battle-tested lodash.debounce internally so the edge cases (leading edge, max wait, trailing edge) are already handled.

useDebounce — Debounce a Value

The most common case: you have a value that changes rapidly and you want a second, lagging copy of it that only updates after things settle. That second copy is what you feed into expensive work.

import { useState, useEffect } from 'react';

import { useDebounce } from '@reactuses/core';



function Search() {

  const [query, setQuery] = useState('');

  const debouncedQuery = useDebounce(query, 300);



  useEffect(() => {

    if (!debouncedQuery) return;

    fetchResults(debouncedQuery);

  }, [debouncedQuery]);



  return (

    <input

      value={query}

      onChange={(e) => setQuery(e.target.value)}

      placeholder="Search…"

    />

  );

}

The signature is useDebounce(value, wait?, options?) and it returns the debounced value, with the same type as the input:

const debounced = useDebounce(value, 300);

The input (query) updates on every keystroke, so the controlled <input> stays perfectly responsive — that's the value you bind to the DOM. The output (debouncedQuery) only catches up 300 ms after the user stops typing, so it's the value you put in the effect's dependency array. The API fires once per pause instead of once per keystroke, and your input never feels laggy because the thing you typed into was never the thing being debounced.

This pattern — fast value for the UI, debounced value for the side effect — is the whole point. Keep them as two separate variables and the rest falls into place.

useDebounceFn — Debounce a Callback

Debouncing a value is great when the thing you want to throttle is state. But sometimes you want to debounce an action that takes arguments — an autosave, an analytics event, a resize handler — without routing it through state first. That's goes deeper.)

The Rate-Limiting Family

useDebounce has three close relatives in ReactUse; pick by what you're limiting and which shape you need:

The throttle pair mirrors the debounce pair exactly — same (value/fn, wait, options) signature, same return shapes — but enforces a steady cadence instead of waiting for silence. Use throttle for things that should update during a continuous gesture (scroll position, drag coordinates, a live progress readout); use debounce for things that should update only after it ends (search, autosave, validation). The full mental model is in and delete your clearTimeout boilerplate.