Suggest an edit

Improve this article

Refine the answer for “What setTimeout() does and returns”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`setTimeout()` is a task scheduling function: it registers a callback with the environment's external API, starts a timer, and once the timer fires, puts the callback into the macrotask queue.** It returns a timer identifier that you can use to cancel the execution with `clearTimeout()`.

## Theory

### TL;DR
- `setTimeout` schedules a one time execution of a function after a given delay.
- The timer itself is run not by the JavaScript engine but by the browser's Web API or the Node.js Timer API.
- After the timer fires, the callback enters the **macrotask queue**, it does not run immediately.
- The delay is a minimum: the callback waits until the call stack is free.
- It returns a timer identifier for `clearTimeout()`.

### Quick example

```javascript
console.log('Start');

setTimeout(() => {
  console.log('after 2 seconds');
}, 2000);

console.log('End');
```

Execution order:

```javascript
Start
End
after 2 seconds
```

Why:

- JavaScript first runs all the synchronous code.
- `setTimeout` only *schedules* the task.
- After 2000 ms the callback enters the **task queue**.
- When the stack is empty, the event loop runs the callback.

### What setTimeout does

1. **Registers the callback** (a function) with the **Web API** or the **Node.js Timer API**.
2. Starts a **timer** for the given time in milliseconds.
3. Once that time is up, it **adds the callback to the macrotask queue (task queue)**.
4. The callback runs **only when** the **call stack becomes free**.

Syntax:

```javascript
setTimeout(callback, delay, ...args);
```

Parameters:

- `callback` is the function to run;
- `delay` is the delay in milliseconds, it does not guarantee exact timing;
- `...args` are extra arguments passed to the `callback`.

### What setTimeout returns

The function **returns a timer identifier**, a unique value you can use to cancel the execution with `clearTimeout()`.

```javascript
const timerId = setTimeout(() => {
  console.log('I will not make it');
}, 5000);

clearTimeout(timerId); // cancel the timer
```

After `clearTimeout(timerId)` the callback **never runs**.

An environment detail: in the browser it is an integer, in Node.js it is a `Timeout` object. In both cases you simply pass the value to `clearTimeout()` and should not rely on its type.

### Important details

#### Minimum delay

Even `setTimeout(..., 0)` does not run instantly:

```javascript
setTimeout(() => console.log('B'), 0);
console.log('A');
```

Output:

```javascript
A
B
```

Because even with `delay = 0` the callback is added to the **macrotask queue** and runs **only after the stack is clear** and **all microtasks** (`Promise.then` and the like) have run.

#### It does not guarantee exact timing

If JavaScript is busy running another function, the timer is "late":

```javascript
setTimeout(() => console.log('I am late!'), 1000);

const start = Date.now();
while (Date.now() - start < 5000) {} // block the thread for 5 seconds
```

The callback fires **after 5 seconds**, not after 1, because the stack was busy.

#### You can pass arguments

```javascript
setTimeout((a, b) => {
  console.log(a + b);
}, 1000, 5, 7);
// prints 12 after one second
```

### Summary

| What it does | What it returns | Where it runs | Queue |
| --- | --- | --- | --- |
| Schedules a function to run after a given delay | A timer identifier | In the Web API (browser) or the Node Timer API | Macrotasks (task queue) |
| Can be cancelled | `clearTimeout(timerId)` | | |

### Common mistakes

- Treating `delay` as exact timing. It is a minimum delay, the real one depends on how busy the stack is.
- Expecting `setTimeout(fn, 0)` to run before `Promise.then`. Microtasks always take priority over macrotasks.
- Calling the callback right away: `setTimeout(fn(), 1000)` instead of `setTimeout(fn, 1000)`. The first form schedules the call's result, not the function.
- Losing the timer identifier and then having no way to cancel the task with `clearTimeout()`.
- Confusing it with `setInterval`: `setTimeout` fires once, repetition is something you schedule yourself.
- Assuming nested timers keep a zero delay. After the fifth level of nesting browsers clamp the minimum to about 4 ms.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts674 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.