Debounce & Throttle

Browsers can fire input, scroll, pointer, and resize events dozens of times per second. If every event triggers filtering, layout reads, analytics, or network requests, the interface starts dropping frames. Debounce and throttle are small control-flow patterns that reduce noisy event streams without changing the rest of your component architecture.

Debounce

Debounce waits until activity has paused. A search box is the classic case: users care about the final query after they stop typing, not every intermediate keypress.

type AnyFn<TArgs extends unknown[]> = (...args: TArgs) => void;

export function debounce<TArgs extends unknown[]>(
  fn: AnyFn<TArgs>,
  delayMs: number,
) {
  let timeoutId: ReturnType<typeof setTimeout> | undefined;

  return (...args: TArgs) => {
    if (timeoutId) clearTimeout(timeoutId);
    timeoutId = setTimeout(() => fn(...args), delayMs);
  };
}

const search = debounce((query: string) => {
  void fetch(`/api/search?q=${encodeURIComponent(query)}`);
}, 300);

The closure keeps the current timeout. Each call cancels the old one and schedules a new one, so only the last call survives.

Throttle

Throttle allows one execution per interval. It is better for scroll and resize work because you want regular updates while the action continues.

export function throttle<TArgs extends unknown[]>(
  fn: AnyFn<TArgs>,
  intervalMs: number,
) {
  let lastCall = 0;

  return (...args: TArgs) => {
    const now = Date.now();
    if (now - lastCall < intervalMs) return;
    lastCall = now;
    fn(...args);
  };
}

const measureViewport = throttle(() => {
  console.log(window.innerWidth, window.scrollY);
}, 100);

window.addEventListener("resize", measureViewport);
window.addEventListener("scroll", measureViewport, { passive: true });

React Hook Wrapper

Hooks usually debounce values rather than event handlers, which makes effects easier to reason about.

import { useEffect, useState } from "react";

export function useDebounce<T>(value: T, delayMs: number): T {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delayMs);
    return () => clearTimeout(id);
  }, [value, delayMs]);

  return debounced;
}

Further Learning

Search these terms to go deeper:

• “debounce vs throttle JavaScript” — practical timing diagrams and event examples
• “requestAnimationFrame scroll handler” — frame-aligned alternatives for visual updates
• “React useDebounce hook cleanup” — hook lifecycle and stale update prevention
• “passive event listeners scroll performance” — why scroll handlers should not block scrolling

Debounce & Throttle

Some events fire like crazy — typing, scrolling, resizing can trigger dozens of times a second. If you run expensive work (like an API call) on every one, your app stutters. Debounce and throttle are two ways to calm that flood.

Debounce: “wait until they stop”

Debounce waits for a pause before running. Perfect for a search box — you don’t want to search on every keystroke, just once the user stops typing:

function debounce(fn, delay) {
  let timer
  return (...args) => {
    clearTimeout(timer)              // cancel the previous wait
    timer = setTimeout(() => fn(...args), delay)  // restart the wait
  }
}

const search = debounce(query => fetch('/api/search?q=' + query), 300)

Each keystroke resets the timer, so the search only fires 300ms after the last one. One call instead of twenty.

Throttle: “at most once every X”

Throttle lets the work run at a steady pace — at most once per interval. Perfect for scroll or resize, where you want regular updates while it’s happening:

function throttle(fn, interval) {
  let last = 0
  return (...args) => {
    const now = Date.now()
    if (now - last < interval) return   // too soon, skip
    last = now
    fn(...args)
  }
}

Which one?

• Debounce = “only care about the final result” → search boxes, autosave.
• Throttle = “want steady updates during the action” → scroll position, resize.

In one sentence

Debounce waits until activity stops before running (great for search), while throttle runs at most once per interval (great for scroll/resize) — both tame events that fire too often.

Want to go deeper?

Switch to Expert mode above for the useDebounce React hook, requestAnimationFrame alternatives, and cleanup details.