Debounce vs Throttle, Explained With Code
Two concepts I did not know about early in my web dev journey, and how to tell them apart with a few lines of JavaScript.
Some of the most useful ideas in web development are the ones nobody mentions at the start. Debounce and throttle were that for me: I did not know either existed until the lack of them started causing problems. They sound alike and solve a similar problem, but they behave very differently, and mixing them up is an easy way to build something that feels broken.
The problem: events fire far more than you need
A user types the word react into a search box. Without any limiting, that is five input events and five network requests, and four of them are for text the user has already moved past. A scroll handler is worse: it can fire dozens of times a second. Debounce and throttle are two ways to say run this less often.
Debounce
Every new call cancels the previous timer and starts a fresh one. The function only runs when a full wait has passed without another call.
function debounce(fn, wait) {
let timer;
const debounced = (...args) => {
clearTimeout(timer);
timer = setTimeout(() => fn(...args), wait);
};
debounced.cancel = () => clearTimeout(timer);
return debounced;
}
input.addEventListener("input", debounce(search, 300));Throttle
A throttled function runs right away, then ignores calls until the interval is over. It keeps updating while the events continue, just less often.
function throttle(fn, wait) {
let last = 0;
return (...args) => {
const now = Date.now();
if (now - last >= wait) {
last = now;
fn(...args);
}
};
}
window.addEventListener("scroll", throttle(updateProgress, 100));Which one should I use
| Situation | Use | Why |
|---|---|---|
| Search as you type | Debounce | You only need the text once the user pauses |
| Autosaving a draft | Debounce | Save after the pause, not after every key |
| Recalculating layout on resize | Debounce | Wait until resizing has stopped |
| Tracking scroll position | Throttle | You need updates while scrolling, only fewer of them |
| Mouse move or dragging | Throttle | Steady updates keep the motion smooth |
| A button people tap repeatedly | Throttle | Ignore repeats inside the window |
Gotchas
- 01Do not recreate it on every renderIn React, a new debounced function on each render has a fresh timer, so it never debounces anything. Create it once with useMemo and keep the function it wraps stable.
- 02Clean up when the component goes awayA pending timer can fire after unmount. Call cancel in an effect cleanup.
- 03Pick a wait that fits the jobAround 200 to 300 ms feels right for search. For scroll, 100 to 200 ms is a common start. Too long and the interface feels laggy.
- 04For animation, use the frameIf the work is visual, such as moving something on scroll, requestAnimationFrame is often a better limiter than a fixed number of milliseconds.
const runSearch = useCallback((text) => {
fetchResults(text);
}, []);
const debouncedSearch = useMemo(
() => debounce(runSearch, 300),
[runSearch]
);
useEffect(() => () => debouncedSearch.cancel(), [debouncedSearch]);Debounce when you only care about the final value. Throttle when you care about the updates along the way, just fewer of them.