Projects Blog About Contact

AbortController

frontendabortcontrollerfetchcancellationbrowser-api

AbortController is the web platform’s shared cancellation primitive. It started as the cancellation mechanism for fetch, but it now appears across event listeners, streams, timers in some runtimes, and many library APIs. Its value is not just stopping network requests. It gives frontend code a consistent way to model ownership: when a component, route, interaction, or operation ends, everything attached to its signal should stop.

The mental model has two pieces. An AbortController owns an AbortSignal. Consumers receive the signal. When the owner calls abort(), the signal flips to aborted, stores a reason, and notifies listeners exactly once.


flowchart TD
  A[Operation owner] --> B[AbortController]
  B --> C[AbortSignal]
  C --> D[fetch]
  C --> E[event listeners]
  C --> F[stream reader]
  C --> G[custom async work]
  B --> H[abort reason]

Fetch cancellation

The most common use is cancelling stale requests:

let currentController;

async function search(query) {
  currentController?.abort(new DOMException("stale search", "AbortError"));
  currentController = new AbortController();

  try {
    const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`, {
      signal: currentController.signal,
    });
    return await response.json();
  } catch (error) {
    if (error.name === "AbortError") return null;
    throw error;
  }
}

Aborting does not mean the server never saw the request. It means the client is no longer interested and the browser should stop the fetch if possible. Server-side work may continue unless your backend detects disconnects and cancels work too.

Event listener cleanup

Signals are excellent for DOM listener lifetimes:

function mountDialog(dialog) {
  const controller = new AbortController();
  const { signal } = controller;

  document.addEventListener("keydown", onKeydown, { signal });
  window.addEventListener("resize", onResize, { signal });

  return () => controller.abort();
}

This avoids storing callback references solely to remove listeners later. It also groups cleanup: one abort tears down all listeners registered with the signal.

Custom async functions

If you write async helpers, accept a signal. Check it before starting expensive work, listen for abort during work, and remove abort listeners in cleanup.

function throwIfAborted(signal) {
  if (signal?.aborted) {
    throw signal.reason ?? new DOMException("Aborted", "AbortError");
  }
}

async function delay(ms, { signal } = {}) {
  throwIfAborted(signal);
  return new Promise((resolve, reject) => {
    const id = setTimeout(resolve, ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(id);
      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
    }, { once: true });
  });
}

For production helpers, remove listeners when the operation completes normally to avoid retaining closures longer than necessary.

Composing cancellation

Real operations often have multiple cancellation causes: route change, user cancel, timeout, or parent operation abort. Modern browsers support helpers such as AbortSignal.timeout() and AbortSignal.any() in many environments, but feature-detect or polyfill if needed.

const signal = AbortSignal.any([
  routeController.signal,
  AbortSignal.timeout(8000),
]);

await fetch("/api/report", { signal });

Use abort reasons to distinguish outcomes. A timeout may show a retry message. A route-change abort should usually stay silent.

Streams

Abort signals pair naturally with streams. If the user closes a streaming panel, abort the fetch and cancel the reader. Put cleanup in finally because stream code has multiple exit paths.

const controller = new AbortController();
const response = await fetch("/api/events", { signal: controller.signal });
const reader = response.body.getReader();

// Aborting the controller errors the fetch; also cancel the reader so the
// stream releases its resources promptly.
controller.signal.addEventListener("abort", () => reader.cancel());

try {
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    handleChunk(value);
  }
} finally {
  reader.releaseLock();
}

Failure modes

Reusing a controller is a common bug. Once aborted, a signal stays aborted forever. Create a new controller for each operation.

Another bug is catching all errors as aborts. Check error.name, compare with signal.reason, or use a small helper. Network failures, CORS failures, and server errors need different handling.

Aborting after an operation already completed is harmless, but it can confuse logs if you record every abort as a failure. Track operation state or treat late aborts as cleanup.

Finally, cancellation is cooperative for your own code. Calling abort() will not stop a CPU-bound loop unless the loop checks the signal and yields.

Debugging

Log operation ids with abort reasons. Many race bugs happen when request A returns after request B and overwrites state. Cancellation reduces the window, but you should still guard state commits by checking that the operation is current.

if (controller.signal.aborted || operationId !== latestOperationId) return;
setResults(data);

In DevTools, aborted fetches may appear as canceled. That is expected when the user changed context.

Component ownership pattern

In UI code, create controllers at the same level that owns the work. A route-level controller should cancel route data, route-level streams, and route-level listeners. A button-level controller should cancel only that click’s operation. Mixing scopes causes subtle bugs: a route change might cancel a still-valid global notification stream, or a retry button might abort every request on the page.

For React-style effects, the cleanup function is the natural owner boundary:

useEffect(() => {
  const controller = new AbortController();
  loadUser(userId, { signal: controller.signal }).then(setUser, handleError);
  return () => controller.abort(new DOMException("component unmounted", "AbortError"));
}, [userId]);

Keep abort reasons boring and machine-readable. They are for branching, metrics, and debugging, not user-facing copy.

API design guidelines

If a function can take noticeable time, accept { signal } even if the first implementation only uses fetch. That keeps cancellation composable when the helper later adds a retry, a stream parser, or a local delay. Check the signal synchronously at the start so callers do not wait for an operation that was already canceled.

Use one cancellation direction: owners abort children. A lower-level helper should not abort a signal it did not create. It may stop its own work when the signal aborts, and it may throw the abort reason, but ownership stays with the caller. This rule prevents surprising cases where a failed child cancels unrelated sibling work.

For multiple child operations, decide whether failure of one child should abort the group. A search page might abort old requests when a new query starts. A dashboard might allow one card to fail while others continue. The controller hierarchy should encode that product decision.

Metrics and observability

Track aborts separately from failures. A high abort rate during typeahead can be healthy because stale searches are being canceled. A high timeout abort rate is a reliability problem. A high route-change abort rate may reveal prefetch work that starts too eagerly.

Include operation id, owner scope, and abort reason in debug logs. Without those fields, cancellation can look like random network instability. With them, races become visible: request 41 was canceled because request 42 superseded it, and request 41 correctly did not commit state.

Checklist

  • Create one controller per owned operation.
  • Pass signal into fetch, listeners, streams, and custom async helpers.
  • Treat abort as a normal outcome for route changes and stale interactions.
  • Use abort reasons to distinguish timeout, user cancel, and stale work.
  • Never reuse an aborted signal.
  • Make CPU-heavy custom work check the signal between chunks.
  • Guard state commits from stale operations even when using cancellation.
  • Clean up abort listeners inside long-lived helper functions.
comments powered by Disqus