Debounce & throttle

Limit noisy event work

Some browser events fire very often. An input event fires on every key press. scroll, resize, mousemove, and pointermove can fire many times per second. Often the user only sees one real change at the end.

Some work is slow or costly. Examples are sending a request to a server, measuring the page, a big calculation, or drawing part of the page again. If that work runs on every event, the browser gets busy and the page feels slow.

The table compares these three wrappers, plus a fourth choice: using CSS instead of JavaScript. Each row says how often the work runs and where it fits.

The timers lesson showed how to cancel a timer. The classic utilities lesson built tiny versions of debounce and throttle. This lesson builds full versions, the kind a real app uses. They add:

• leading and trailing calls: running at the start or at the end of a wait,
• maxWait: the longest the function may wait,
• keeping this and the arguments,
• cancel() and flush(), to throw away or finish waiting work,
• tests with a fake clock, so every run gives the same result.

You can still listen to every event. Noticing an event is cheap. The costly work inside the handler is what needs a limit: network requests, changes to the page, and updates to your app's data. That work only needs to run as often as the user can notice.

1const debounced = debounce(updateSearch, 400);2const throttled = throttle(updateScroll, 300);3const visual = rafThrottle(updatePointerPreview);4 5function onNoisyEvent(value) {6  rawCount += 1;7  debounced(value);  // waits for quiet8  throttled(value);  // at most once per interval9  visual(value);     // once per animation frame10}

Type quickly in the box, then stop. The Raw count goes up on every key press. The Debounced count waits until you stop. Now move the pointer inside the pad. The rAF count goes up at most once per frame, and it always uses the newest pointer position. The main thread lesson explains why each change to the page should be small and planned like this.

Use debounce when only the final value matters, not the values in between. For example:

• a search box that searches for the finished word, not for every letter,
• autosave after the user stops typing,
• checking a form field after the user pauses,
• work that should run once the user stops resizing the window.

The examples in this lesson use a fake clock, made by createFakeClock(). It works like real timers, but time only moves when you call clock.tick(ms). So every run prints the same thing. Each wrapper takes the clock as its last argument.

const clock = createFakeClock();
const search = debounce((term) => console.log("search:", term), 100, {}, clock);

search("c");
search("ca");
search("cat");
clock.tick(100);

Line 2 makes one debounced wrapper called search, with a wait of 100 milliseconds. Lines 4 to 6 call it three times in a row. Each call replaces the saved search word. Line 7 moves the fake clock forward 100 milliseconds. The wait ends, and the real function runs once. It prints search: cat. Only the last word reaches the function.

const clock = createFakeClock();
const fired = [];
const save = debounce((value) => fired.push(clock.now() + "ms " + value), 100, { leading: true, trailing: true }, clock);

save("draft");
clock.tick(40);
save("final");
clock.tick(100);
console.log(fired.join(" | "));

Line 3 turns on both leading and trailing. Line 5 calls save("draft"). Leading is on, so it runs right away, at 0ms. Line 7 calls again at 40ms, with final. That call came during the wait, so a trailing call runs 100ms later, at 140ms. Line 9 prints 0ms draft | 140ms final.

Here is the full debounce. Its first two arguments are the real function, fn, and the wait in milliseconds. The last argument, clock, lets the tests pass in the fake clock. In a browser it uses the real Date.now, setTimeout, and clearTimeout.

1function debounce(fn, wait, options = {}, clock = { now: Date.now, setTimeout, clearTimeout }) {2  const leading = options.leading === true;3  const trailing = options.trailing !== false;4  const maxing = typeof options.maxWait === "number";5  const maxWait = maxing ? Math.max(options.maxWait, wait) : undefined;6  let timerId, maxTimerId, lastArgs, lastThis, result;7 8  function invoke() {9    const args = lastArgs;10    const receiver = lastThis;11    lastArgs = lastThis = undefined;12    result = fn.apply(receiver, args);13    return result;14  }15 16  function finishWait() {17    timerId = undefined;18    if (maxTimerId !== undefined) clock.clearTimeout(maxTimerId);19    maxTimerId = undefined;20    if (trailing && lastArgs) return invoke();21    lastArgs = lastThis = undefined;22    return result;23  }24 25  function finishMaxWait() {26    maxTimerId = undefined;27    if (timerId !== undefined) clock.clearTimeout(timerId);28    timerId = undefined;29    if (lastArgs) return invoke();30    return result;31  }32 33  function debounced(...args) {34    const callLeading = leading && timerId === undefined;35    lastArgs = args;36    lastThis = this;37    if (timerId !== undefined) clock.clearTimeout(timerId);38    timerId = clock.setTimeout(finishWait, wait);39    if (maxing && maxTimerId === undefined) maxTimerId = clock.setTimeout(finishMaxWait, maxWait);40    return callLeading ? invoke() : result;41  }42 43  debounced.cancel = () => {44    if (timerId !== undefined) clock.clearTimeout(timerId);45    if (maxTimerId !== undefined) clock.clearTimeout(maxTimerId);46    timerId = maxTimerId = lastArgs = lastThis = undefined;47  };48  debounced.flush = () => {49    if (timerId === undefined && maxTimerId === undefined) return result;50    if (timerId !== undefined) clock.clearTimeout(timerId);51    if (maxTimerId !== undefined) clock.clearTimeout(maxTimerId);52    timerId = maxTimerId = undefined;53    return trailing && lastArgs ? invoke() : result;54  };55  return debounced;56}

Here is what the main lines do:

• Lines 2 and 3 read the options. leading is off unless you turn it on. trailing is on unless you turn it off.
• Lines 8 to 14 are invoke(), which runs the real function. Line 12 uses fn.apply(receiver, args). apply calls a function with a chosen this and a list of arguments. So a method still gets its own object as this, and the function gets the newest arguments.
• Lines 35 and 36 save the newest arguments and this on every call.
• Line 37 cancels the old timer, and line 38 starts a new one. This is the "wait starts again" rule.
• Line 39 starts a second timer for maxWait. It starts only once per burst, which is a group of calls close together. This timer makes sure the function still runs while someone types without stopping.
• Lines 43 and 48 add cancel() and flush(). The section on real apps shows how to use them.

1const clock = createFakeClock();Run2const fired = [];3const search = debounce((term) => {4  fired.push(clock.now() + "ms " + term);5}, 100, { trailing: true }, clock);6 7search("a");8clock.tick(40);9search("ab");10clock.tick(40);11search("abc");12clock.tick(99);13clock.tick(1);14console.log(fired.join(" | "));

In the first timeline, calls come at 0, 40, and 80 milliseconds. Later calls cancel the first two timers. The last timer is never canceled, so it ends at 180 milliseconds, and only abc runs. Pick the other choices to see leading calls and maxWait.

Use throttle when work should keep happening while events keep coming, just not on every event. For example:

• a bar that shows how far down the page you have scrolled,
• a handler that moves something while you drag it,
• a button that may only act once per second,
• analytics that record what the user does, now and then.

The time period throttle waits between runs is called the interval. In the examples below it is 100 milliseconds.

1function throttle(fn, interval, options = {}, clock = { now: Date.now, setTimeout, clearTimeout }) {2  const leading = options.leading !== false;3  const trailing = options.trailing !== false;4  let timerId, lastArgs, lastThis, lastInvokeTime, result;5 6  function invoke(time) {7    const args = lastArgs;8    const receiver = lastThis;9    lastArgs = lastThis = undefined;10    lastInvokeTime = time;11    result = fn.apply(receiver, args);12    return result;13  }14 15  function scheduleTrailing(remaining) {16    if (!trailing || timerId !== undefined) return;17    timerId = clock.setTimeout(() => {18      timerId = undefined;19      if (lastArgs) invoke(clock.now());20    }, remaining);21  }22 23  function throttled(...args) {24    const time = clock.now();25    lastArgs = args;26    lastThis = this;27    if (lastInvokeTime === undefined) {28      lastInvokeTime = time;29      return leading ? invoke(time) : (scheduleTrailing(interval), result);30    }31    const remaining = interval - (time - lastInvokeTime);32    if (remaining <= 0) {33      if (timerId !== undefined) clock.clearTimeout(timerId);34      timerId = undefined;35      return invoke(time);36    }37    scheduleTrailing(remaining);38    if (!trailing) lastArgs = lastThis = undefined;39    return result;40  }41 42  throttled.cancel = () => {43    if (timerId !== undefined) clock.clearTimeout(timerId);44    timerId = lastArgs = lastThis = lastInvokeTime = undefined;45  };46  throttled.flush = () => {47    if (timerId === undefined) return result;48    clock.clearTimeout(timerId);49    timerId = undefined;50    return lastArgs ? invoke(clock.now()) : result;51  };52  return throttled;53}

Throttle remembers when the real function last ran, in lastInvokeTime (line 4). On each call:

• Lines 25 and 26 save the newest arguments and this.
• Line 31 works out how much of the interval is left.
• If no time is left (line 32), the function runs now (line 35).
• If some time is left, line 37 starts one timer for the time that is left. It does this only when trailing is on and no timer is waiting yet.

Later calls during the interval only replace the saved arguments. So when the timer ends, the function runs with the newest event data.

const clock = createFakeClock();
const positions = [];
const trackScroll = throttle((position) => positions.push(position), 100, {}, clock);

trackScroll(10);
clock.tick(20);
trackScroll(80);
clock.tick(80);
console.log(positions.join(" -> "));

Line 5 sends position 10. It is the first call, so it runs right away. Line 7 sends 80 at 20ms. That is inside the 100ms interval, so it waits. Line 8 moves the clock to 100ms. The interval ends, and the saved 80 runs. Line 9 prints 10 -> 80.

1const clock = createFakeClock();Run2const fired = [];3const track = throttle((position) => {4  fired.push(clock.now() + "ms " + position);5}, 100, { leading: true, trailing: true }, clock);6 7track("top");8clock.tick(20);9track("middle");10clock.tick(50);11track("bottom");12clock.tick(30);13clock.tick(20);14track("after");15clock.tick(80);16console.log(fired.join(" | "));

See how this differs from debounce. While the calls keep coming, the throttled function runs at 0ms, 100ms, and 200ms. It does not wait for the calls to stop. It runs at a steady pace.

A time throttle works well when the interval is a rule you choose, like "at most once per second". Work that changes what the user sees is different. The browser draws the page in frames, often about 60 times per second. It does not draw on a 100ms schedule.

requestAnimationFrame(callback) asks the browser to run callback just before it draws the next frame. rAF throttle uses it like this:

• On the first call, ask the browser for one frame.
• On later calls before that frame, only replace the saved arguments.
• When the frame comes, run the real function once, with the newest arguments.

Use it for a preview that follows the pointer, for drawing on a canvas, or for moving things as the page scrolls.

1function rafThrottle(fn, raf = { requestAnimationFrame, cancelAnimationFrame }) {2  let frameId;3  let lastArgs;4  let lastThis;5  let result;6 7  function invoke() {8    const args = lastArgs;9    const receiver = lastThis;10    frameId = lastArgs = lastThis = undefined;11    result = fn.apply(receiver, args);12    return result;13  }14 15  function throttled(...args) {16    lastArgs = args;17    lastThis = this;18    if (frameId === undefined) frameId = raf.requestAnimationFrame(invoke);19    return result;20  }21 22  throttled.cancel = () => {23    if (frameId !== undefined) raf.cancelAnimationFrame(frameId);24    frameId = lastArgs = lastThis = undefined;25  };26  throttled.flush = () => frameId === undefined ? result : (raf.cancelAnimationFrame(frameId), invoke());27  return throttled;28}

Line 18 asks for one frame, but only if no frame is waiting yet. Lines 16 and 17 save the newest arguments on every call. Line 23 cancels a frame that has not run yet, with cancelAnimationFrame. That matters when a component is removed from the page or a Reset button clears everything.

The next example passes in a fake frame clock, frameClock. Instead of waiting for the browser, it saves each frame callback in the frames list.

const frames = [];
const frameClock = {
  requestAnimationFrame(callback) {
    frames.push(callback);
    return frames.length;
  },
  cancelAnimationFrame() {},
};
const panel = { width: 0 };
const resizePanel = rafThrottle((width) => {
  panel.width = width;
}, frameClock);

resizePanel(800);
resizePanel(900);
frames.shift()();
console.log(panel.width);

Lines 14 and 15 send two widths, 800 and 900, before any frame runs. Only one frame was asked for. Line 16 runs that frame by hand. It uses the latest width, so line 17 prints 900. In a real browser, the frame runs just before the next drawing.

Many apps use Lodash, a popular library of helper functions, instead of writing their own. Its _.debounce and _.throttle work like the versions in this lesson:

• They have leading and trailing options. Debounce also has maxWait.
• The real function gets the arguments from the last call.
• The wrapper has .cancel() and .flush().

Lodash even builds its throttle out of its debounce, with maxWait set to the same time as the wait. That shows how close the two ideas are.

Each row of the next table is one thing to get right in a real app: what to do, and why it matters.

A search box often sends a request with fetch. An AbortController can stop a request that has already started. You pass its signal to fetch, and later call abort() on the controller.

1let currentRequest;2const searchLater = debounce(async (term) => {3  currentRequest?.abort();4  currentRequest = new AbortController();5  const response = await fetch("/api/search?q=" + encodeURIComponent(term), {6    signal: currentRequest.signal,7  });8  renderResults(await response.json());9}, 250);10 11input.addEventListener("input", (event) => searchLater(event.target.value));12window.addEventListener("beforeunload", () => {13  searchLater.cancel();14  currentRequest?.abort();15});

• Line 2 makes a debounced search that waits 250 milliseconds.
• Line 3 stops the previous request, if there is one.
• Line 4 makes a new controller for this request, and line 6 links the request to it.
• Lines 13 and 14 run when the page is closing. Line 13 cancels a search that is still waiting. Line 14 stops a request that has already started.

The wrapper has two methods for waiting work. cancel() throws away the waiting call. flush() runs the waiting call right now, instead of waiting.

const clock = createFakeClock();
const saved = [];
const save = debounce((value) => saved.push(value), 100, {}, clock);

save("old");
save.cancel();
clock.tick(100);
save("new");
save.flush();
console.log(saved.join(" | "));

Line 6 cancels the save of old, so it never runs. Line 7 moves the clock, and nothing happens. Line 8 saves new. Line 9 flushes it, so it runs right away. Line 10 prints new.

Debounce only controls when a request starts. It does not control the order the answers come back in. An older, slower request can still answer last. So stop the old request, or give each request a number and ignore answers to old numbers. The cancellation lesson covers AbortController in depth. The memory management lesson explains why to clean up when a component is removed from the page.

• Making the wrapper inside the event handler. The timer is stored in the wrapper. A new wrapper has a new timer, so it can't cancel the timer from the last event.
• Losing this. If the real function is a method, call it with fn.apply(thisArg, args). A plain fn(...args) loses the object the method belongs to.
• Using old arguments. The trailing call should use the newest event data, not the arguments from the first call.
• Forgetting cleanup. Waiting timers, frames, and requests can still change a component after it is removed from the page. Cancel them when it is removed.
• Thinking debounce keeps answers in order. Debounce delays when requests start. Answers from the network can still come back in any order.
• Calling flush() during cleanup. flush() runs the waiting call on purpose. Cleanup usually needs cancel() instead.
• Thinking a passive listener is a throttle. A passive listener helps scrolling stay smooth. It does not make the handler run less often.

1// Bug: this creates a new wrapper for every event.2input.addEventListener("input", (event) => {3  debounce(() => search(event.target.value), 300)();4});5 6// Fix: create one wrapper and reuse it.7const debouncedSearch = debounce((value) => search(value), 300);8input.addEventListener("input", (event) => {9  debouncedSearch(event.target.value);10});

Line 3 makes a new wrapper on every input event and calls it right away. Each wrapper has its own timer, so every key press still searches. Line 7 makes one wrapper. Line 9 calls that same wrapper on every event, so all the calls share one timer.

The table below sums up each option. Read a row to see when the function runs and where the option helps.

Choose by how often the user needs to see a change:

• Only the final value, after a pause? Use debounce.
• Regular updates while events keep coming? Use throttle.
• Changes to what is drawn on the screen? Use rAF throttle.
• Can CSS do the job? Then don't use JavaScript for it at all.

Key takeaways

• Debounce waits until the calls stop, then runs once with the arguments from the last call.
• Throttle runs at most once per interval. With trailing on, it also runs the newest saved call at the end of the interval.
• A leading call runs at the start of a wait, and a trailing call runs at the end. maxWait makes debounce run even while calls never stop.
• rAF throttle is best for work that changes what is drawn, because it runs once per frame.
• Make each wrapper once, keep this and the arguments, cancel waiting work when you clean up, and stop old requests.

Next, the Performance stage moves on to DOM and rendering performance. You will learn how the browser lays out and draws the page, and how to avoid work it doesn't need to do.