AbortController: cancelling fetches, timeouts and event listeners

Starting an asynchronous operation is easy. Stopping one you no longer care about is the part most code skips, and it is where memory leaks, race conditions and stale results come from. AbortController is the browser's single answer to all of it.

One controller, one signal

MDN defines it plainly: the AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired. The shape is always the same. You create a controller, read its signal, and hand that signal to whatever you are starting.

The signal property returns an AbortSignal object instance, which can be used to communicate with, or to abort, an asynchronous operation. The controller is the thing you keep; the signal is the thing you give away.

const controller = new AbortController();

const res = await fetch('/api/articles', { signal: controller.signal });

// somewhere else, later:
controller.abort();

Note the direction. The code doing the work never decides to stop; it only agrees to listen. That separation is what lets one caller cancel many operations at once.

The two errors, and why it matters

This is the part worth reading carefully, because the same cancellation can throw two different things.

When you call abort() yourself, the fetch() promise rejects with a DOMException named AbortError. When the signal came from AbortSignal.timeout(), the fetch() promise rejects with a TimeoutError DOMException instead.

So the familiar check is incomplete:

try {
  const res = await fetch(url, { signal });
} catch (err) {
  if (err.name === 'AbortError') {
    // the user or our own code cancelled it
  } else if (err.name === 'TimeoutError') {
    // the deadline passed - a different situation entirely
  } else {
    throw err; // a real network or parsing failure
  }
}

Collapsing the two loses real information. A user navigating away is not a problem; a request that ran out of time probably is, and is worth reporting or retrying. Code that only looks for AbortError treats every timeout as a silent non-event.

Timeouts without the plumbing

The pattern most people still write pairs a controller with a setTimeout and a clearTimeout in a finally block. It works, and it is no longer necessary.

AbortSignal.timeout() returns an AbortSignal instance that will automatically abort after a specified time. No controller, no timer to clear, nothing to leak:

// Old: three moving parts
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5000);
try {
  const res = await fetch(url, { signal: controller.signal });
} finally {
  clearTimeout(timer);
}

// Now: one
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });

Watch the error name when you make this swap. The old version threw AbortError; the new one throws TimeoutError, so any catch block you already had will need updating.

The trick most people miss: event listeners

AbortSignal is not a fetch feature. addEventListener accepts a signal in its options, and when that signal aborts, the listener is removed for you. This quietly replaces the most tedious cleanup code in front-end work.

Compare removing listeners by hand, which requires keeping a reference to every function you passed:

// Before: you must keep every handler to remove it
function onScroll() { /* ... */ }
function onResize() { /* ... */ }
window.addEventListener('scroll', onScroll);
window.addEventListener('resize', onResize);

function teardown() {
  window.removeEventListener('scroll', onScroll);
  window.removeEventListener('resize', onResize);
}

With a signal, the handlers can be inline again, and one call removes all of them:

const controller = new AbortController();
const { signal } = controller;

window.addEventListener('scroll', () => { /* ... */ }, { signal });
window.addEventListener('resize', () => { /* ... */ }, { signal });
document.addEventListener('keydown', () => { /* ... */ }, { signal });

// one call removes all three
controller.abort();

The same controller can also be holding the signal for an in-flight fetch. Tearing down a view then becomes a single abort() that cancels the request and unbinds every listener together.

Combining signals, and reading state

AbortSignal.any() returns an AbortSignal that aborts when any of the given abort signals abort. That is how you get a deadline and a manual cancel on the same operation:

const controller = new AbortController();

const signal = AbortSignal.any([
  controller.signal,          // the user pressed Cancel
  AbortSignal.timeout(10000), // or ten seconds passed
]);

const res = await fetch(url, { signal });

A signal also tells you where it stands. aborted is a Boolean that indicates whether the request(s) the signal is communicating with is/are aborted, and reason is a JavaScript value providing the abort reason, once the signal has aborted. Passing your own reason to abort() is how you distinguish causes later:

controller.abort(new Error('User navigated away'));

// later
if (signal.aborted) console.log(signal.reason.message);

There is also an abort event, invoked when the asynchronous operations the signal is communicating with is/are aborted, which lets your own long-running code cooperate rather than only built-in APIs.

Making your own function abortable

Anything that takes a signal joins the same system. The pattern is to check aborted before starting and to listen for the abort event while running:

function wait(ms, { signal } = {}) {
  return new Promise((resolve, reject) => {
    if (signal?.aborted) return reject(signal.reason);
    const id = setTimeout(resolve, ms);
    signal?.addEventListener('abort', () => {
      clearTimeout(id);
      reject(signal.reason);
    }, { once: true });
  });
}

Now your own helper can be cancelled by the same controller that cancels your fetches, which is the whole point of there being one mechanism rather than several.

Quick reference

Goal	Call
Cancel manually	controller.abort(), throws AbortError
Add a deadline	AbortSignal.timeout(ms), throws TimeoutError
Either of the two	AbortSignal.any([a, b])
Auto-remove a listener	addEventListener(type, fn, { signal })
Check state	signal.aborted
Find out why	signal.reason
React to cancellation	the abort event

AbortController is a small API that quietly solves a large category of cleanup problems. Hand one signal to your requests, your listeners and your own async helpers, then stop all of them with a single call. Just remember which error you are catching, because a manual abort and an expired deadline are not the same event.

For the request side of this, see our guide to the Fetch API in JavaScript.