Keeping the main thread responsive

One thread does many jobs

A thread is one line of work that a computer runs, one step after another. In a browser tab, most jobs share one thread, called the main thread. It does all of these:

• It runs your page's JavaScript.
• It handles input: clicks, taps, and key presses.
• It works out the styles and the layout (where each box goes on the page).
• It paints: it draws a new picture of the page on the screen.

The main thread does one job at a time. Each job is called a task. While one JavaScript task runs, nothing else can happen. A click waits. Typing waits. The page does not paint, so the screen looks frozen.

Plain definition: keeping the main thread responsive means keeping every task short, so input and painting get a turn often. When a job is too big for one turn, you have three choices:

• Split it into small pieces, called chunks, with a break between them.
• Run it later, when the browser has nothing else to do.
• Move heavy number work to a Web Worker, which is a second thread that runs JavaScript.

This lesson uses ideas from The event loop, Microtasks in depth, Timers, and Web Workers. It also points to Animation, Typed arrays, Measuring performance, and the next lesson, Debounce & throttle.

A long task is a task on the main thread that runs for 50 ms or more. (ms means milliseconds; 1000 ms is one second.) A screen usually shows about 60 pictures each second, so one picture has about 16 ms. A 50 ms task is three pictures long. People can feel that, mostly on slower phones.

A simple guide to the time budgets, called the RAIL model, says:

• Answer input quickly, so a click feels instant.
• Keep each animation frame very short.
• Do extra work only when the browser is free.
• Do not let page loading block a click.

INP means Interaction to Next Paint. It measures how long the page takes to answer a click, a tap, or a key press. The time starts at the input and ends when the next picture of the page is painted. INP has three parts:

The table shows each part: what the page waits for, and what can make it shorter.

In March 2024, INP replaced an older score, First Input Delay, as one of the Core Web Vitals. These are the main speed scores that Google tracks for real users. A good INP is 200 ms or less for at least 75 out of 100 real visits (the 75th percentile). That is why a test on one fast laptop is not enough: real users have slower devices.

1const observer = new PerformanceObserver((list) => {2  for (const entry of list.getEntries()) {3    console.log(entry.entryType, Math.round(entry.duration));4  }5});6 7const types = PerformanceObserver.supportedEntryTypes;8if (types.includes("longtask")) {9  observer.observe({ type: "longtask", buffered: true });10}11if (types.includes("long-animation-frame")) {12  observer.observe({ type: "long-animation-frame", buffered: true });13}

A PerformanceObserver is an object that the browser calls when it records a new timing entry. Here is what the code does, line by line:

1. Lines 1 to 5 make the observer. For each entry, it prints the entry type and its length in ms.
2. Line 7 reads supportedEntryTypes, the list of entry types this browser can record.
3. Lines 8 to 10 watch longtask entries, but only if the browser supports them.
4. Lines 11 to 13 watch long-animation-frame entries: frames that took too long to paint. Only Chrome-like browsers have them, so the code checks first.

buffered: true also gives you entries recorded before the observer started. Use these entries together with DevTools and data from real users, as the Measuring performance lesson shows.

1performance.mark("search-start");2filterVisibleRows();3performance.mark("search-end");4performance.measure("search", "search-start", "search-end");5 6new PerformanceObserver((list) => {7  for (const entry of list.getEntriesByName("search")) {8    console.log(entry.name, Math.round(entry.duration));9  }10}).observe({ type: "measure" });

1. Line 1 sets a named point in time, a mark, called search-start.
2. Line 2 runs the search.
3. Line 3 sets a second mark, search-end.
4. Line 4 makes a measure called search: the time between the two marks.
5. Lines 6 to 10 watch for measures and print the name and the time of search.

The time depends on the device, so the printed number changes from run to run. Compare runs with each other instead of expecting one exact number.

To yield means to stop your work for a moment, let the browser do other jobs, and then go on. Where you stop matters:

• If you stop and go on in a new task, the browser can handle input and paint in between.
• If you go on in a microtask (a short follow-up job, such as a promise's .then() callback), the browser usually cannot paint in between.

Each way to yield differs in which browsers have it, how urgent the next part is, and how soon your work goes on.

1async function yieldToMainThread() {2  if (globalThis.scheduler?.yield) {3    await globalThis.scheduler.yield();4    return "scheduler.yield";5  }6  await new Promise((resolve) => setTimeout(resolve, 0));7  return "setTimeout fallback";8}9 10yieldToMainThread().then((mode) => {11  console.log("yielded with " + mode);12});

1. Line 2 checks if this browser has scheduler.yield. Checking first like this is called feature detection.
2. Lines 3 and 4 wait for scheduler.yield(), then return its name.
3. Lines 6 and 7 are the fallback, the backup plan: they wait for a setTimeout with 0 ms, which runs in a new task, then return its name.
4. Lines 10 to 12 print which way was used.

scheduler.yield() pauses an async function and goes on again soon, and it keeps the work's place near the front of the line. Chrome has it from version 129, and Firefox from version 142. Safari does not have it. Because not every browser has it, real code checks first and keeps the setTimeout fallback.

1const schedulerApi = globalThis.scheduler;2 3if (schedulerApi?.postTask) {4  schedulerApi.postTask(5    () => console.log("background task"),6    { priority: "background" },7  );8} else {9  setTimeout(() => console.log("fallback task"), 0);10}

scheduler.postTask() queues a new task with a priority, a label for how urgent it is. Line 3 checks for it. Lines 4 to 7 queue a task with the priority "background", which means "not urgent". Line 9 is the fallback timer for browsers without it.

The table compares the ways to yield. Read each row as one tool.

setTimeout(fn, 0) works in every browser because it queues a new task. The Timers lesson explains one catch: after a few timers inside timers, browsers wait at least about 4 ms each time. Some libraries use MessageChannel instead, which avoids that wait. The Scheduler API (scheduler.yield and scheduler.postTask) adds priorities where a browser has it.

Chunking is the usual way to handle a big array: do a small piece, yield, then go on. The function below, processInChunks, is a real helper from this lesson. It takes three options:

• budgetMs: the time budget, how many ms one chunk may use before it yields.
• clock: the thing that tells the time. By default it is performance.
• yieldFn: the function that yields. By default it is yieldToMainThread.

You can pass in your own clock and your own yield function. Tests and the step-through below use a pretend clock, so every run gives the same result.

1async function processInChunks(items, work, options = {}) {2  const budgetMs = Math.max(1, options.budgetMs ?? 8);3  const clock = options.clock ?? performance;4  const yieldFn = options.yieldFn ?? yieldToMainThread;5  let index = 0;6 7  while (index < items.length) {8    const started = clock.now();9    do {10      work(items[index], index);11      index += 1;12    } while (index < items.length && clock.now() - started < budgetMs);13 14    if (index < items.length) {15      await yieldFn();16    }17  }18}

1. Lines 2 to 4 read the options, or use the defaults.
2. Line 7 keeps going while items are left.
3. Line 8 notes the time when this chunk starts.
4. Lines 9 to 12 work on one item at a time. They stop when no items are left or the chunk has used up its budget.
5. Lines 14 to 16 yield, but only if items are still left.

1const jobs = [Run2  { label: "A", cost: 2 },3  { label: "B", cost: 3 },4  { label: "C", cost: 2 },5  { label: "D", cost: 4 },6  { label: "E", cost: 1 },7];8 9await processInChunks(jobs, (job) => {10  doWork(job.label);11  clock.advance(job.cost);12}, {13  budgetMs: 5,14  clock,15  yieldFn: () => yieldToBrowser(),16});

The step-through uses five jobs, A to E. Each job has a pretend cost in ms. The budget is 5 ms.

• A (2 ms) and B (3 ms) fill the first chunk: exactly 5 ms.
• C (2 ms) and D (4 ms) make the second chunk: 6 ms. That is 1 ms over, because a chunk always finishes the job it started.
• E (1 ms) finishes the last chunk. No items are left, so there is no last yield.

1setTimeout(() => console.log("timer task"), 0);Run2let count = 0;3function scheduleNext() {4  count += 1;5  console.log("microtask " + count);6  if (count < 3) {7    Promise.resolve().then(scheduleNext);8  }9}10Promise.resolve().then(scheduleNext);11console.log("script done");

This short promise loop shows a common mistake from the Microtasks lesson: a promise chain does not give the browser a chance to paint. The browser runs every waiting microtask before it paints. So long work must yield to a new task, or move off the main thread.

requestIdleCallback(fn) asks the browser to call fn when it is idle, which means it has nothing else to do. The browser passes your function a deadline object. deadline.timeRemaining() tells you how many ms of free time are left.

• Pass a timeout option if the work must happen at some point. It sets the longest time the browser may wait.
• Safari does not have requestIdleCallback. So check for it first, and keep a fallback.

1function scheduleIdleFlush(queue) {2  const run = (deadline) => {3    while (deadline.timeRemaining() > 0 && queue.length > 0) {4      sendAnalytics(queue.shift());5    }6    if (queue.length > 0) scheduleIdleFlush(queue);7  };8 9  if ("requestIdleCallback" in window) {10    return requestIdleCallback(run, { timeout: 2000 });11  }12 13  return setTimeout(() => run({ timeRemaining: () => 3 }), 1);14}

1. Line 2 makes run, the function the browser calls when it is free.
2. Lines 3 to 5 send one item at a time, while free time is left and the queue is not empty.
3. Line 6 asks for another free moment if items are still left.
4. Lines 9 to 11 use requestIdleCallback if the browser has it, and wait at most 2000 ms.
5. Line 13 is the fallback: a timer that pretends there are 3 ms of free time.

requestAnimationFrame(fn) has a different job. It calls fn just before the next paint. Use it for visual work: reading where an animation is, moving an element with a transform, or drawing one frame on a canvas. The Animation lesson covers it in depth.

A timeout is not the same as free time. When the timeout runs out, the browser calls your idle function even if it is busy. So keep that function short too.

Chunks still run on the main thread. Some jobs are heavy number work for the processor (the CPU), and they only turn input data into output data. For those jobs, a worker may be a better place. A worker is a second thread that runs JavaScript.

• A worker cannot read the layout or change the DOM (the page's elements).
• A worker can parse, search, sort, compress, and work on raw bytes, while the main thread keeps answering the user.

1// main thread2const worker = new Worker(workerUrl);3worker.postMessage({ type: "filter", query: "Ada", rows });4worker.onmessage = (event) => {5  renderRows(event.data.matches);6};7 8// worker.js9self.onmessage = (event) => {10  const { query, rows } = event.data;11  const matches = rows.filter((row) => row.name.includes(query));12  self.postMessage({ matches });13};

1. Line 2 starts a worker from the file workerUrl.
2. Line 3 sends the worker a message: the job type, the search word "Ada", and the rows.
3. Lines 4 to 6 wait for the reply and put the matches on the page with renderRows.
4. Lines 9 to 13 are the worker file. It reads the message, keeps the rows whose name includes the word, and sends back { matches }.

The table asks the questions to check before you move work to a worker. For each one, it shows a good sign and a warning sign. A transferable value, such as an ArrayBuffer of bytes, is handed over to the worker instead of being copied.

1const result = { matches: ["Asha", "Asha's team"] };2console.log(result.matches.join(", "));3// The worker sends data; the main thread renders it.

The worker can send back the matching names. But only the main thread can change the page's DOM, so it does the last step. This example only shows the shape of the code, because the lesson editor cannot load a worker file or a full app page.

The Web Workers lesson covers how workers start and stop, how messages are copied, transferables, module workers, and errors. The Typed arrays lesson explains the byte buffers that often make sending data to a worker worth it.

Each run below does about half a second of busy CPU work. While it runs, type in the box and watch the spinner and the counter.

• Blocking runs all the work as one long task.
• Chunked does the same work in small chunks, with a yield between them.
• Worker runs the busy loop in a real worker and gets a reply when it is done.

1const modes = ["blocking", "chunked", "worker"];2 3// Blocking: one long task. Input, paint, and timers wait.4runButton.onclick = () => doCpuWork(450);5 6// Chunked: same total work, but yield between slices.7await processInChunks(items, work, {8  budgetMs: 24,9  yieldFn: yieldToMainThread,10});11 12// Worker: CPU work happens on another thread.13worker.postMessage({ ms: 450 });

Where you will use this

Real apps need this often. Here are some examples:

• A search page filters a long list.
• An admin tool reads a big export file.
• An image editor changes pixels.
• A dashboard sends analytics in batches.
• A code editor colors many lines of code.

Which tool fits depends on four things: how urgent the work is, whether it needs the DOM, how much data there is, and whether the work already waits for something, like a network reply.

1const names = ["Asha", "Ben", "Asha's team"];2const matches = names.filter((name) => name.includes("Asha"));3console.log(matches.join(", "));

Two names in the array contain Asha, so the output is Asha, Asha's team. For a much bigger list, keep the same filter but run it in chunks, or move the search work to a worker. Do not move the DOM updates into that worker.

The table matches common jobs to the tool you would try first.

Common mistakes

1button.addEventListener("click", () => {2  spinner.hidden = false;3  Promise.resolve().then(() => {4    expensiveLoop();5  });6});

Line 2 shows the spinner. Lines 3 to 5 put the slow loop in a promise callback, which is a microtask. The browser runs that microtask before it paints. So the spinner may not show up until the slow work is already done.

Key takeaways

• The main thread runs JavaScript, handles input, works out style and layout, and paints. It does one task at a time.
• A long task is 50 ms or more. It delays input and makes INP worse. A good INP is 200 ms or less for at least 75 out of 100 visits.
• Microtasks do not let the page paint. A long promise loop can still freeze the page.
• Split big arrays into chunks with a time budget, and yield with scheduler.yield or a fallback timer.
• Use requestIdleCallback only for work that can wait, with a timeout and a fallback.
• Move heavy data work to a worker when it is worth the cost of starting it and sending messages.

Up next: Debounce & throttle. There you will stop slow event handlers from starting too often in the first place.