Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Events

The once and signal listener options

Reference for the once and signal options of addEventListener(): run a handler a single time, or remove many listeners at once with an AbortController signal.

addEventListener() accepts an options object as its third argument. Two of its options handle clean-up so you do not have to keep references for removeEventListener().

once: true runs the listener at most one time and then removes it automatically. signal takes an AbortSignal; when its AbortController calls abort(), the listener is removed. One signal can be shared by any number of listeners, so you can detach a whole group with one call.

JavaScript
button.addEventListener("click", start, { once: true });

const controller = new AbortController();
window.addEventListener("keydown", onKey, { signal: controller.signal });
window.addEventListener("resize", onResize, { signal: controller.signal });
controller.abort();   // removes both

Try it

once: a handler that runs a single time
signal: remove several listeners with one abort()

Syntax

JavaScript
target.addEventListener(type, listener, { once: true });
target.addEventListener(type, listener, { signal: abortSignal });
target.addEventListener(type, listener, { capture, once, passive, signal });

Options

Option Type Description
capture boolean Listen during the capture phase instead of the bubble phase.
once boolean Remove the listener after it has been called once. Default false.
passive boolean Promise not to call preventDefault(). See passive listeners.
signal AbortSignal Remove the listener when the signal is aborted.

Usage notes

  • once removes the listener before it runs. If the handler itself throws, it still counts as used. If it triggers the same event again, the listener will not run a second time.
  • A signal that is already aborted means addEventListener() adds nothing at all.
  • No need to keep the function. With removeEventListener() you must pass the same function and capture flag. With signal, anonymous arrow functions are fine.
  • Group clean-up. Create one AbortController per component, page section or modal, pass its signal to every listener, and call abort() when it closes. This prevents leaked listeners.
  • Combine signals. AbortSignal.any([a, b]) aborts when either does, and AbortSignal.timeout(ms) aborts after a delay. These are newer static methods, so check a compatibility table.
  • Works elsewhere. Many web APIs accept a signal too, for example fetch(), so one abort() can cancel a request and its listeners together.
  • once with Promises. A one-off event fits a Promise: new Promise((resolve) => el.addEventListener("load", resolve, { once: true })).
  • signal does not abort the handler. It only stops future calls; a handler that is already running keeps running.

Browser support

The once and signal options are supported in all current browsers. AbortSignal.any() and AbortSignal.timeout() are newer: check a compatibility table before using them.