JavaScript addEventListener, Beyond the Basics
September 4, 2026
- Javascript
Most code only ever calls addEventListener with two arguments: an event
name and a callback. That covers 90% of cases, but the parts people skip
— the options object, delegation, and how removal actually works — are
where the interesting bugs live.
The basic shape
button.addEventListener('click', (event) => {
console.log('clicked', event.target);
});event.target is the actual element the event happened on. event.currentTarget
is the element the listener is attached to — inside the handler these are
often the same, but they diverge as soon as you're using delegation.
The third argument
addEventListener takes an options object as its third argument, and each
flag changes real behavior:
element.addEventListener('scroll', handler, {
capture: false,
once: false,
passive: false,
signal: undefined,
});A bare true instead of an object is still supported and means
{ capture: true } — that's a holdover from the old two-value API and
still shows up in older code and some library internals.
capture
Events normally fire during the bubble phase — from the target
outward. capture: true fires the listener during the capture phase
instead, on the way in, before the target itself is reached.
outer.addEventListener('click', () => console.log('outer capture'), { capture: true });
inner.addEventListener('click', () => console.log('inner bubble'));Clicking inner logs outer capture first, then inner bubble. This
matters when you need to intercept an event before a child's own handler
(or stopPropagation) can run.
once
Removes the listener automatically after it fires a single time — no
manual removeEventListener call needed:
button.addEventListener('click', () => {
console.log('only once');
}, { once: true });passive
Tells the browser the listener will never call preventDefault(), which
lets it start scrolling immediately instead of waiting to see if you
cancel it. It matters most on touchstart, touchmove, and wheel:
element.addEventListener('touchstart', handler, { passive: true });Some browsers already default touchstart/touchmove to passive for
performance. If you actually need to call preventDefault() inside one of
these, don't pass passive: true — it will be ignored and the browser
will warn you in the console.
signal
Ties the listener's lifetime to an AbortController, so you can remove it
— along with any number of other listeners — with a single call:
const controller = new AbortController();
element.addEventListener('mousemove', onMove, { signal: controller.signal });
window.addEventListener('resize', onResize, { signal: controller.signal });
// later, removes both listeners at once
controller.abort();This is the cleanest way to clean up listeners tied to a component's
lifecycle — no need to keep the original function reference around just
so you can pass it to removeEventListener later.
removeEventListener needs the same reference
The most common reason removeEventListener silently fails is that the
function passed to it isn't the same function reference used in
addEventListener — an anonymous function or an arrow function created
inline can never be removed this way.
// This never removes anything — a new function is created each time.
button.addEventListener('click', () => console.log('hi'));
button.removeEventListener('click', () => console.log('hi'));
// This works, because the reference is stable.
function onClick() {
console.log('hi');
}
button.addEventListener('click', onClick);
button.removeEventListener('click', onClick);removeEventListener also has to match capture — a listener added with
{ capture: true } won't be removed by a call that omits it.
Event delegation
Instead of attaching a listener to every item in a list, attach one
listener to a shared ancestor and check event.target to figure out what
was actually clicked. This also automatically covers items added later.
document.querySelectorAll('li').forEach((li) => {
li.addEventListener('click', () => console.log(li.textContent));
});
// New <li> elements added later need their own listener attached manually.event.target.closest('li') handles clicks on nested markup inside the
<li> — a <span> or icon inside it — that event.target === li alone
would miss.
Stopping propagation vs preventing default
These are two unrelated things people often reach for interchangeably:
| Method | What it actually does |
|---|---|
event.preventDefault() | Cancels the browser's default action (following a link, submitting a form) |
event.stopPropagation() | Stops the event from bubbling to ancestor listeners |
event.stopImmediatePropagation() | Also stops other listeners on the same element from running |
Calling preventDefault() does not stop propagation, and stopPropagation()
does not cancel the default action — if you need both, call both.
A quick checklist
- Use
{ once: true }instead of manually removing a listener that should only fire once. - Use
{ passive: true }on touch/wheel listeners that never callpreventDefault(). - Prefer
{ signal }with anAbortControllerfor grouped cleanup over tracking individual function references. removeEventListenerneeds the exact same function reference (and matchingcapture) that was passed toaddEventListener.- Delegate listeners to a shared ancestor for lists, and use
event.target.closest(selector)to find the actual item clicked.
MDN: addEventListener