How the browser event loop works

A page's JavaScript, its event handlers and most of the work of drawing it share a single thread: the main thread. It can only do one thing at a time.

The event loop is the rule that decides what that one thing is. Picture it as the bridge in the middle of this machine. It turns from lane to lane and lets one piece of work at a time onto the call stack, the only place where code runs.

When a task starts, its function goes on the call stack. Every call it makes adds a frame on top, and every return takes the top frame off. Here a click handler calls update(), which calls log().

Nothing can interrupt this. However many tasks are waiting, the loop cannot start the next one until the stack is empty again. JavaScript calls the rule run-to-completion.

setTimeout, fetch and addEventListener do not wait. Each hands a job to the browser (count down, talk to a server, watch the mouse) and returns at once, so the stack empties and the main thread is free.

The waiting happens in other parts of the browser, off the main thread. When a timer runs out, a response arrives or the user clicks, the browser does not interrupt your code. It queues a task.

A task is one unit of work for the main thread: run a script, dispatch a click, call a timer's callback, deliver a network response.

Tasks wait in a queue, and the loop takes exactly one per turn, oldest first. Browsers keep several task queues and may serve one ahead of another, such as input before timers, but tasks from the same source never overtake each other.

Promise callbacks (then, and whatever follows an await) are not tasks. They are microtasks, with a queue of their own.

As soon as a task finishes and the stack is empty, the loop runs every microtask in that queue, including any that those microtasks add. Only then does it move on. A microtask that keeps queuing another starves everything else: no task runs and no frame is drawn.

A click handler runs two lines: setTimeout(later, 0) and Promise.resolve().then(sooner). Which callback runs first?

sooner does, every time. The promise's callback is a microtask, so it runs the moment the handler returns. The timer's callback is a task: it joins the back of the task queue and waits for a turn of its own, behind everything already in line. Zero milliseconds means as soon as possible, not now.

Between tasks the browser checks whether it is time to update the screen, usually 60 times a second. If it is, the loop runs requestAnimationFrame callbacks, then recomputes style, lays the page out and paints it.

Until that happens, nothing you changed is visible. A handler can add a class, remove it and add it again; only the state left when the loop reaches the render steps is ever drawn.

Seen from above, the whole machine is one cycle.

Take the oldest task and run it until the stack is empty. Run every microtask. If a frame is due, run the animation callbacks and render. Then go round again, or wait if nothing is queued.

Everything a page does on the main thread is some part of this turn.

Because the loop cannot leave a task half done, one slow function holds up everything behind it. While this 200 ms task runs, twelve screen refreshes pass with nothing new to show, and a click that arrives 30 ms in waits 170 ms for its handler.

The page is not broken, only busy. To the person using it, it is frozen. Browsers count any task of 50 ms or more as a long task.

The fix is to give the loop its turn back. Split long work into short tasks and the loop can paint a frame or handle a click between any two of them. The same 200 ms of work no longer blocks anything.

Waiting on a promise is not enough, because microtasks run before the loop moves on. Yield with a new task instead (setTimeout, or scheduler.yield() where it exists), or move the work to a Web Worker, which has an event loop of its own.