Timers: setTimeout & setInterval

A timer is a reminder, not a pause

JavaScript runs one piece of code from start to end before it does anything else. A timer doesn't stop that code. Instead, you hand a function to the host. The host is the program that runs your JavaScript, such as the browser or Node.js. The host waits. Later, it calls your function.

A function that you hand over to be called later is a callback. You met callbacks in the previous lesson. The host does the waiting. The callback runs only after the code that is running now has finished.

This lesson uses four functions:

• setTimeout runs a callback once, later.
• setInterval runs a callback again and again.
• clearTimeout and clearInterval cancel a timer that you no longer want.

You will also measure real delays in this tab. The numbers change from one computer to another. A slow computer, a hidden tab, battery saving, or a page that is still loading can all make a timer late.

setTimeout(callback, delay) takes a callback and a delay. The delay is in milliseconds (ms), and 1000 ms is one second. setTimeout sets the timer and gives back an id right away. An id is a value that names this one timer:

• In a browser, the id is a number.
• In Node.js, the id is a Timeout object.

Save the id if you might want to cancel the timer. You can also pass more values after the delay. The host passes them to the callback when it runs.

setTimeout((name, count) => {
  console.log(name + " has " + count + " reminders");
}, 1000, "Ada", 3);

Line 3 passes "Ada" and 3 after the delay of 1000 ms. One second later, line 1 gets them as name and count. Line 2 prints Ada has 3 reminders.

A repeating timer works the same way: set it, save the id, and cancel it with the id. The callback below counts three ticks and then stops its own interval.

let count = 0;
const id = setInterval(() => {
  count += 1;
  console.log("tick", count);
  if (count === 3) clearInterval(id);
}, 5);

Line 2 saves the id in id before the first tick. Every 5 ms, line 3 adds one to count and line 4 prints it. On the third tick, line 5 passes the same id to clearInterval, so there is no fourth tick.

The next code sets three timers, cancels one, and prints two lines of its own. Step through it and watch when each line prints. A timer with a delay of 0 still runs later, not in the middle of the script.

1console.log("A: start");Run2const keep = setTimeout(() => console.log("D: 20ms timeout"), 20);3const cancel = setTimeout(() => console.log("never runs"), 10);4setTimeout(() => console.log("C: 0ms timeout"), 0);5clearTimeout(cancel);6console.log("B: end");

The picture shows the three timers that lines 2 to 4 hand to the browser, and the one that line 5 cancels.

Cancelling matters most when you clean up. Say the user presses Reset, leaves the page, or closes part of the page. Clear every timer that is still waiting. If you don't, an old callback can run later and change a page that has moved on.

Now test the "at least" rule yourself. The lab below sets a 500 ms timer. Then it can run a busy loop: a loop that keeps JavaScript busy for a set time. While the loop runs, nothing else can run, not even a timer that is due.

1const started = performance.now();2const id = setTimeout(() => {3  const actual = performance.now() - started;4  console.log(actual);5}, 500);6 7// Optional: block the thread before the callback can run.

setInterval(fn, 500) tries to start fn every 500 ms. That works well for a clock, or for a small check that repeats. But say the work sometimes takes longer than 500 ms. The interval doesn't wait for it. The next callback can start while the last one's work is still going.

A nested timeout is a setTimeout whose callback sets the next timer when its work is done. So each wait starts only after the work ends.

setInterval(async () => {
  await saveSlowly();
}, 500);

async function loop() {
  await saveSlowly();
  timeoutId = setTimeout(loop, 500);
}

Lines 1 to 3 use setInterval. Every 500 ms, it starts a new call to saveSlowly(), even if the last save hasn't finished. Lines 5 to 8 use a nested timeout. Line 6 waits for the save with await. Only then does line 7 set the next timer, 500 ms away.

Try both below. Each tick does 150 ms of pretend work, and the bars show when each tick really starts.

1let intervalId;2let intervalTicks = 0;3let timeoutId;4let timeoutTicks = 0;5 6function doSlowWork() {7  const end = performance.now() + 150;8  while (performance.now() < end) {}9}10 11intervalId = setInterval(() => {12  intervalTicks += 1;13  console.log("interval", intervalTicks);14  doSlowWork();15  if (intervalTicks === 2) clearInterval(intervalId);16}, 500);17 18function nestedTick() {19  timeoutTicks += 1;20  console.log("nested", timeoutTicks);21  doSlowWork();22  if (timeoutTicks < 2) timeoutId = setTimeout(nestedTick, 500);23}24 25timeoutId = setTimeout(nestedTick, 500);

So how do you choose?

• Use setInterval for small, steady ticks, like a clock.
• Use a nested timeout when each run must finish before the next wait starts.
• Use a nested timeout when the next delay changes each time.

A delay of 0 means "as soon as the browser allows". It doesn't mean "right now". Browsers also have rules about the shortest wait, to protect the page and the computer. When a browser raises a delay that is too small up to a minimum, that is called clamping.

One rule comes from the HTML standard, the rule book that browsers follow. A timer that is set inside another timer's callback is nested. After five levels of nesting, each wait is at least 4 ms. Your measured numbers may be bigger, or they may jump around.

1let depth = 0;2let last = performance.now();3 4function next() {5  const now = performance.now();6  console.log(depth, now - last);7  last = now;8  depth += 1;9  if (depth < 10) setTimeout(next, 0);10}11 12setTimeout(next, 0);

A negative delay, a missing delay, or NaN ("not a number") doesn't throw an error. The host treats it as a very short delay, like 0. The callback still runs later, and it can still wait behind other code. So use plain, sensible numbers for delays. For a reminder on a calendar date, check the date instead of setting one long timer.

Clearing twice is safe. If you call clearTimeout twice with the same id, nothing breaks and nothing runs again. So a Reset button and a clean-up step can both clear the same timer.

Here is the rule you can trust: a timer waits at least the delay you asked for. It can run later when:

• the script that is running now is still busy,
• another callback is running,
• the tab is hidden and the browser slows its timers down,
• or the computer is busy with other work.

Browsers often slow the timers in a hidden tab down to about once per second. Some browsers slow them even more.

That is why every demo in this lesson measures time with performance.now(). It gives the number of milliseconds since the page opened. The results you see are measured on this computer, in this tab, when you click. They are not copied from someone else's computer.

A hidden tab may pause its timers or slow them down to save battery. So don't count ticks to know how much time has passed. For a countdown, save the time when it should end. Each time a callback runs, work out end - performance.now() and show that.

Timer callbacks also have a rule about this. Inside a method, this is the object before the dot, like user in user.start(). But the host calls a timer callback on its own, with no object before the dot. So a normal function callback doesn't get your object as this. An arrow function has no this of its own. It uses the this of the code around it.

const user = {
  name: "Asha",
  start() {
    setTimeout(() => console.log(this.name), 0);
  },
};

user.start();

Line 8 calls user.start(), so inside start, this is user. The arrow callback on line 4 uses that same this. So when it runs, it prints Asha.

In Node.js, the id has extra methods, such as unref(). They belong to Node.js, not to browsers. To keep your code working everywhere, only pass the id to the matching clear function.

Some tools can be stopped with an abort signal. An abort signal is an object that says "stop now" once it is aborted. fetch, which loads data from a server, is one of these tools.

const controller = new AbortController();
const timeout = AbortSignal.timeout(1000);
console.log(timeout.aborted);
controller.abort();
console.log(controller.signal.aborted);

Line 1 makes an AbortController, an object you can abort by hand. Line 2 makes a signal that aborts itself after 1000 ms. Line 3 prints false, because no time has passed yet. Line 4 aborts the controller by hand, so line 5 prints true.

The table puts the timer functions side by side. Read each row as: this function runs this, you cancel it like this, and it gives back this.

Where you’ll use timers

Timers show up all over web pages. You use them to:

• hide a small pop-up message after a few seconds,
• wait for the user to stop typing before you search,
• ask a server for new data again and again,
• show a countdown,
• or stop a loading spinner if something takes too long.

Two other lessons go deeper. Closures in loops, timers & memory explains a common trap with loop variables. Losing this explains why setTimeout(obj.method) loses its object.

To poll a server means to ask it for new data again and again. The code below polls with a nested timeout, so two requests never overlap.

let timeoutId;
let stopped = false;

async function poll() {
  await loadLatestData();
  if (!stopped) timeoutId = setTimeout(poll, 1000);
}

poll();

function stopPolling() {
  stopped = true;
  clearTimeout(timeoutId);
}

Line 5 waits for the data to load. Line 6 sets the next timer, but only if polling hasn't stopped. stopPolling does two things: line 12 sets stopped to true, so no new timer is set, and line 13 cancels the timer that is waiting. Real apps call it from a Reset button, or when the user leaves the page.

Debounce means waiting for a quiet moment before you act. A search box can use it, so three quick key presses cause one save, not three. A similar idea is throttle: let an action run at most once in each time window. Throttle suits updates while the user scrolls or resizes the window. The small debounce below keeps only the last value.

let timerId;
function saveSearch(text) {
  clearTimeout(timerId);
  timerId = setTimeout(() => console.log("save", text), 10);
}

saveSearch("c");
saveSearch("ca");
saveSearch("cat");

Each call to saveSearch clears the timer before it on line 3, then sets a new one on line 4. The calls on lines 7 and 8 set timers that the next call clears. Only the timer from line 9 is left, so the code prints save cat once.

For work that changes the page while the user scrolls, requestAnimationFrame is often a better fit. It runs your function just before the browser draws the next picture of the page. Timers don't know when the browser draws.

Common mix-ups

• “0 ms means right now.” It means later: after the script ends, when the browser can run the callback.
• “500 ms means exactly 500 ms.” It means at least 500 ms. Busy code and hidden tabs can make it later.
• “An interval waits for my async work.” It doesn't know when your promise finishes. Use a nested timeout, or a flag that skips a tick while the work is still going.
• “Clearing a timer after it ran undoes it.” Clearing only cancels a timer that is still waiting. Once a callback has run, clearing can't undo it.
• “A huge delay is a safe long reminder.” Delays above 2 ** 31 - 1 ms overflow, in Node.js and in browsers.
• “Timer ids look the same everywhere.” Browsers give back numbers. Node.js gives back objects.

Key takeaways

• setTimeout runs a callback once, later. clearTimeout cancels it if it hasn't run yet.
• setInterval repeats until you call clearInterval. A nested timeout waits the full delay after each run's work ends.
• A delay is the shortest wait, not an exact time. Measure with performance.now() when the timing matters.
• Deeply nested timers wait at least 4 ms, hidden tabs slow timers down, and huge delays overflow.
• Clear your timers on Reset, on Stop, and when the user leaves the page.

Final definition: a JavaScript timer is a reminder kept by the host. It runs a callback later, after at least the delay, and it never pauses the code that is running now.

Up next: The event loop.