Debounce vs Throttle in JavaScript: Examples, React Hook and When to Use Each

// Run fn once calls stop for `wait` ms. With { leading: true },
// run on the first call of a burst instead of after it.
export function debounce(fn, wait, { leading = false } = {}) {
  let timer = null;
  let lastArgs;
  let lastThis;

  function debounced(...args) {
    lastArgs = args;
    lastThis = this;
    const callNow = leading && timer === null;
    clearTimeout(timer);
    timer = setTimeout(() => {
      timer = null;
      if (!leading) fn.apply(lastThis, lastArgs);
    }, wait);
    if (callNow) fn.apply(lastThis, lastArgs);
  }

  debounced.cancel = () => {
    clearTimeout(timer);
    timer = null;
  };

  // Run the pending call right away (e.g. before the page unloads)
  debounced.flush = () => {
    if (timer === null || leading) return;
    debounced.cancel();
    fn.apply(lastThis, lastArgs);
  };

  return debounced;
}

import { debounce } from "./debounce.js";

const input = document.querySelector("#search");

const search = debounce((query) => {
  console.log("Searching for", query); // runs once typing pauses for 300 ms
}, 300);

input.addEventListener("input", (event) => search(event.target.value));

// Run on the first click, ignore repeat clicks until 1 s of quiet
const submitOrder = debounce(() => placeOrder(), 1000, { leading: true });
button.addEventListener("click", submitOrder);

const saveDraft = debounce((text) => api.save(text), 2000);
editor.addEventListener("input", () => saveDraft(editor.value));

// Don't lose the last edit when the tab is hidden or closed
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") saveDraft.flush();
});

// Run fn at most once every `wait` ms: immediately on the first call,
// then once more at the end with the latest arguments.
export function throttle(fn, wait) {
  let last = 0;
  let timer = null;
  let lastArgs;
  let lastThis;

  function run() {
    last = Date.now();
    timer = null;
    fn.apply(lastThis, lastArgs);
  }

  function throttled(...args) {
    lastArgs = args;
    lastThis = this;
    const remaining = wait - (Date.now() - last);
    if (remaining <= 0) {
      clearTimeout(timer);
      run();
    } else if (timer === null) {
      timer = setTimeout(run, remaining);
    }
  }

  throttled.cancel = () => {
    clearTimeout(timer);
    timer = null;
    last = 0;
  };

  return throttled;
}

import { throttle } from "./throttle.js";

const reportScroll = throttle(() => {
  analytics.track("scroll", { y: window.scrollY });
}, 200);

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

// For visual updates on scroll/resize: at most once per animation frame
export function rafThrottle(fn) {
  let frame = null;
  let lastArgs;
  return function (...args) {
    lastArgs = args;
    if (frame !== null) return;
    frame = requestAnimationFrame(() => {
      frame = null;
      fn(...lastArgs);
    });
  };
}

const updateProgressBar = rafThrottle(() => {
  const max = document.documentElement.scrollHeight - innerHeight;
  bar.style.transform = `scaleX(${scrollY / max})`;
});
window.addEventListener("scroll", updateProgressBar, { passive: true });

// ❌ A new debounced function on every render: nothing is debounced
function Search() {
  const [query, setQuery] = useState("");
  const search = debounce((q) => fetchResults(q), 300);
  return <input value={query} onChange={(e) => { setQuery(e.target.value); search(e.target.value); }} />;
}

import { useEffect, useState } from "react";

// Returns `value`, but only after it has stopped changing for `delay` ms
export function useDebouncedValue(value, delay = 300) {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id); // a new keystroke cancels the old timer
  }, [value, delay]);

  return debounced;
}

import { useEffect, useState } from "react";
import { useDebouncedValue } from "./useDebouncedValue.jsx";

export function SearchBox() {
  const [query, setQuery] = useState("");
  const debouncedQuery = useDebouncedValue(query.trim(), 300);
  const [results, setResults] = useState([]);

  useEffect(() => {
    if (!debouncedQuery) {
      setResults([]);
      return;
    }
    const controller = new AbortController();
    fetch(`/api/search?q=${encodeURIComponent(debouncedQuery)}`, { signal: controller.signal })
      .then((res) => res.json())
      .then(setResults)
      .catch((err) => {
        if (!controller.signal.aborted) console.error(err);
      });
    return () => controller.abort(); // drop answers to older queries
  }, [debouncedQuery]);

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search…" />
      <ul>
        {results.map((item) => (
          <li key={item.id}>{item.title}</li>
        ))}
      </ul>
    </div>
  );
}

import debounce from "lodash/debounce";
import throttle from "lodash/throttle";

const save = debounce(saveDraft, 2000, { maxWait: 10000 }); // save at least every 10 s
const onScroll = throttle(track, 200, { trailing: false });