HTML Web Workers API

Introduction

Web Workers are a powerful browser feature that let scripts run in the background, separate from the main thread that paints the page and handles clicks. That means you can crunch numbers, parse large files, or process data without freezing scroll, animation, or input.

This tutorial explains what workers are, how to create them, how messaging works, and how to avoid common mistakes—with five examples and three interactive Try It demos you can run in your browser.

What You’ll Learn

What Are Web Workers?

Web Workers are a way to run JavaScript in background threads. Each worker has its own global scope (accessed as self) and runs independently of the main UI thread. You typically use them for:

• Long mathematical or statistical calculations
• Parsing large JSON or CSV files
• Image, audio, or video processing
• Sorting or filtering big arrays
• Prefetching and transforming API data before display

Workers are not separate processes like OS threads in native apps—they are browser-managed threads with a strict security model. They are still one of the best tools for keeping pages responsive in plain JavaScript.

How Do Web Workers Work?

Workers run in their own global context. They cannot access the DOM, window, document, or most browser APIs tied to the visible page. Communication happens through a messaging channel:

• Main thread — creates the worker, sends jobs with worker.postMessage(), listens with worker.onmessage.
• Worker thread — receives jobs in self.onmessage, does the work, replies with self.postMessage().
• Structured clone — message data is copied between threads (objects, arrays, typed arrays). Functions and DOM nodes cannot be sent.

Because the worker is separate, a heavy loop inside it does not block the main thread—buttons stay clickable and animations keep running.

Creating a Web Worker

The classic pattern uses two files. On the main page, instantiate Worker with the URL of a JavaScript file:

const worker = new Worker('worker.js');

In worker.js, write the code that runs in the background thread:

self.onmessage = function (event) {
  const result = performTask(event.data);
  postMessage(result);
};

function performTask(data) {
  // Perform computation or processing here
  return data * 2; // Example: double the input
}

Inline worker (single-file demos)

In the Try It editor you often have only one HTML file. Put the worker code in a string and create a Blob—no <style> or extra files needed:

var code =
  'self.onmessage = function(e) { postMessage(e.data * 2); };';

var worker = new Worker(
  URL.createObjectURL(new Blob([code], { type: 'application/javascript' }))
);

Our Try It demos use this pattern so everything runs in one HTML page without extra server files.

Communicating with Web Workers

Send data from the main thread with postMessage. Receive replies in onmessage:

// main.js
worker.postMessage(5); // Send data to the worker

worker.onmessage = function (event) {
  console.log('Received from worker:', event.data);
};

Inside the worker, mirror the pattern—listen on self.onmessage, reply with postMessage:

// worker.js
self.onmessage = function (event) {
  const squared = event.data * event.data;
  postMessage(squared);
};

You can send plain objects: worker.postMessage({ action: 'sum', values: [1, 2, 3] }). The worker receives a deep copy, not a shared reference.

Handling Errors

Workers can throw runtime errors. Catch them on the main thread with worker.onerror:

worker.onerror = function (error) {
  console.error('Worker error:', error.message);
  console.error('File:', error.filename, 'Line:', error.lineno);
};

Also call worker.terminate() when you no longer need the worker to free memory. Create a new Worker if you need to run jobs again later.

Common Pitfalls

• DOM access — Workers cannot touch the DOM. Send results back to the main thread and update the page there.
• Shared globals — Workers have their own global scope. Variables on window are not visible inside a worker, and vice versa.
• Large message copies — postMessage clones data. Sending huge objects repeatedly can be slow; consider Transferable objects (like ArrayBuffer) for zero-copy moves.
• Same-origin worker scripts — The worker script URL must obey the same-origin policy unless CORS allows it.
• Over-using workers — Spawning a worker for tiny tasks adds overhead. Use workers when work genuinely risks blocking the UI.
• Browser compatibility — Dedicated Workers are widely supported, but always feature-detect and provide a main-thread fallback for critical paths.

Examples Gallery

Five short examples from creating a worker to a full page. Each uses plain JavaScript—no styling required to understand the idea. Try It Yourself demos are minimal HTML with no CSS, using inline Blob workers so you do not need a separate worker.js file.

if (typeof Worker === 'undefined') {
  alert('Web Workers not supported');
} else {
  var worker = new Worker('worker.js');
}

Worker created

var worker = new Worker('worker.js');

worker.postMessage(5);

worker.onmessage = function (event) {
  alert('Worker replied: ' + event.data); // 10
};

self.onmessage = function (event) {
  postMessage(event.data * 2);
};

Received from worker: 10

const worker = new Worker('worker.js');

worker.onerror = function (error) {
  console.error('Worker error:', error.message);
};

worker.onmessageerror = function () {
  console.error('Could not deserialize message from worker');
};

Worker error: Uncaught ReferenceError: unknownVar is not defined

var worker = new Worker('sum-worker.js');

worker.postMessage(1000000); // add 0+1+2+...+999999

worker.onmessage = function (event) {
  document.getElementById('result').textContent = event.data;
};

self.onmessage = function (e) {
  var total = 0, i;
  for (i = 0; i < e.data; i++) {
    total += i;
  }
  postMessage(total);
};

Sum = 499999500000

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Web Worker Example</title>
</head>
<body>
  <h1>Web Worker Example</h1>
  <button id="start">Start Worker</button>
  <p id="result"></p>

  <script>
    var workerCode =
      'self.onmessage = function(e) {' +
      '  postMessage(e.data * e.data);' +
      '};';

    var worker = new Worker(
      URL.createObjectURL(new Blob([workerCode], { type: 'application/javascript' }))
    );

    worker.onmessage = function (event) {
      document.getElementById('result').textContent =
        'Result: ' + event.data;
    };

    document.getElementById('start').onclick = function () {
      worker.postMessage(10);
    };
  </script>
</body>
</html>

Result: 100

🚀 Common Use Cases

• Data crunching — aggregate analytics, sort large tables, or run simulations.
• File parsing — read CSV, JSON, or log files without blocking typing or scrolling.
• Media processing — resize images, decode audio, or build waveform data.
• Real-time apps — keep WebSocket message handling smooth while processing payloads.
• Games and editors — pathfinding, physics ticks, or syntax highlighting in the background.
• Progressive enhancement — move expensive work off the main thread when Worker is available.

📝 Notes

• Workers are not a replacement for server-side scaling—they help one browser tab stay responsive.
• Service Workers (for offline caching) are a different API from Web Workers (for background computation).
• Module workers: new Worker('worker.js', { type: 'module' }) lets worker scripts use import.
• Terminate idle workers with worker.terminate() to avoid leaking threads.
• For tiny tasks (< few ms), main-thread code is often faster than worker startup overhead.
• Try It demos use Blob URLs so you can experiment without uploading separate .js files.

💡 Best Practices