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.
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
Syntax
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
onceremoves 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. Withsignal, anonymous arrow functions are fine. - Group clean-up. Create one
AbortControllerper component, page section or modal, pass its signal to every listener, and callabort()when it closes. This prevents leaked listeners. - Combine signals.
AbortSignal.any([a, b])aborts when either does, andAbortSignal.timeout(ms)aborts after a delay. These are newer static methods, so check a compatibility table. - Works elsewhere. Many web APIs accept a
signaltoo, for examplefetch(), so oneabort()can cancel a request and its listeners together. oncewith Promises. A one-off event fits a Promise:new Promise((resolve) => el.addEventListener("load", resolve, { once: true })).signaldoes 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.
Related
addEventListener()removeEventListener()- passive listeners
- event bubbling and capturing โ the
captureoption - Lesson: AbortController