Debounce vs throttle in React

Both techniques limit how often a function runs. They are not interchangeable, and picking the wrong one produces a UI that feels either laggy or broken.

Debounce: wait for the pause#

A debounced function resets its timer every time it is called. It only actually runs once the calls stop for the full delay. For a search box, that means one request when the user finishes typing rather than one per keystroke.

1import { useState } from 'react';
2import { useDebounce } from '@danixsoft/hooks';
3
4function ProductSearch() {
5  const [query, setQuery] = useState('');
6  const debouncedQuery = useDebounce(query, 300);
7
8  useEffect(() => {
9    if (!debouncedQuery) return;
10    search(debouncedQuery);
11  }, [debouncedQuery]);
12
13  return (
14    <input
15      value={query}                                  // instant feedback
16      onChange={(e) => setQuery(e.target.value)}
17      placeholder="Search products…"
18    />
19  );
20}

The same hook covers autosave, which is the other place debouncing shines — you want one write after the user stops typing, not one per character.

1const [draft, setDraft] = useState('');
2const debouncedDraft = useDebounce(draft, 1000);
3
4// Skips the initial render, so an empty draft is never written.
5useUpdateEffect(() => {
6  saveDraft(debouncedDraft);
7}, [debouncedDraft]);

Throttle: a steady drip#

A throttled function runs immediately, then refuses to run again until the interval has elapsed. Scroll events fire dozens of times a second; a throttled handler turns that into a manageable stream while still updating continuously.

1import { useRef, useCallback } from 'react';
2import { useEventListener } from '@danixsoft/hooks';
3
4function useThrottledScroll(handler: (y: number) => void, ms = 100) {
5  const lastRun = useRef(0);
6
7  const onScroll = useCallback(() => {
8    const now = Date.now();
9    if (now - lastRun.current < ms) return;
10    lastRun.current = now;
11    handler(window.scrollY);
12  }, [handler, ms]);
13
14  useEventListener('scroll', onScroll);
15}

Why the naive React implementation breaks#

The instinct is to wrap the handler in lodash.debounce inside the component. It does not work, and the reason is worth understanding.

1function Broken() {
2  const [query, setQuery] = useState('');
3
4  // ✗ Recreated on every render, so the timer resets and never fires.
5  const debouncedSearch = debounce((value) => search(value), 300);
6
7  return <input onChange={(e) => debouncedSearch(e.target.value)} />;
8}

Each render produces a brand-new debounced function with a brand-new internal timer, so no call ever survives long enough to fire. Wrapping it in useCallback fixes the identity but introduces a stale closure — the memoised function captures the state from the render that created it.

Debouncing the value rather than the callback sidesteps both problems entirely. There is no function identity to preserve and no closure to go stale.

Choosing, in one question#

1. 1

   Do you need updates while the activity is happening?

   Yes → throttle. A progress bar, a follow-the-cursor tooltip and a drag preview all need continuous feedback.

2. 2

   Do you only care about the final value?

   Yes → debounce. Search queries, autosave, form validation and resize-driven layout recalculation only need the settled value.

3. 3

   Is it about an element entering or leaving the viewport?

   Then neither — use IntersectionObserver. It is more accurate and cheaper than any listener you can throttle.