Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Events

EventTarget.addEventListener() method

Reference for addEventListener(): register click, keydown and custom event handlers, use the capture, once, passive and signal options, and avoid common mistakes.

The addEventListener() method registers a function that the browser calls whenever a given type of event reaches an object. It is defined on EventTarget, so it works on elements, document, window, XMLHttpRequest, WebSocket, AbortSignal and many other objects.

You can add as many listeners as you like for the same event type. They run in the order they were added. Unlike the onclick property, adding a listener never replaces an existing one.

JavaScript
target.addEventListener(type, listener);
target.addEventListener(type, listener, options);

Try it

Two listeners on one button
Listening on an object that is not an element

Syntax

JavaScript
addEventListener(type, listener)
addEventListener(type, listener, options)
addEventListener(type, listener, useCapture)

Parameters

Name Description
type A string with the event name, such as "click", "keydown" or "submit". Event names are case-sensitive and have no on prefix.
listener A function, or an object with a handleEvent() method. It receives the Event object as its only argument. It may also be null, in which case nothing is added.
options Optional object with these properties: capture (boolean, listen during the capture phase), once (boolean, remove the listener after its first call), passive (boolean, promise never to call preventDefault()) and signal (an AbortSignal that removes the listener when it aborts).
useCapture Optional boolean. The older form of the third argument, equal to { capture: useCapture }.

Return value

undefined.

Exceptions

  • A TypeError is thrown if listener is neither a function, an object, nor null, or if fewer than two arguments are passed.

Usage notes

  • Duplicates are ignored. If you add the same function with the same type and the same capture value twice, the browser keeps just one registration. Two different function objects (for example two separate arrow functions with the same body) count as two listeners.
  • Removing needs the same function. removeEventListener() only works if you pass the original function reference and the same capture value. An inline arrow function cannot be removed later unless you stored it in a variable, or you used the signal or once option.
  • this in the listener. In a regular function, this is the element the listener was added to (the same as event.currentTarget). In an arrow function, this is whatever it was in the surrounding code, so use event.currentTarget there.
  • passive: true and scrolling. For touchstart, touchmove and wheel listeners on window, document and document.body, browsers treat the listener as passive by default. A passive listener that calls preventDefault() is ignored, and the console logs a warning.
  • Listeners added during dispatch. A listener added to the current target while an event is being dispatched does not run for that same event. A listener removed before its turn is skipped.
  • Errors do not stop other listeners. An exception in one listener is reported to the console, but the remaining listeners still run.
  • Prefer it over onclick. Assigning to element.onclick allows only one handler, and a later assignment replaces the earlier one.
  • Cleaning up many listeners. Pass the same AbortController signal to every listener you add and call controller.abort() once to remove all of them.

Browser support

The two-argument and useCapture forms work in every browser. The options object (capture, once, passive) and the signal option are supported by all current browsers, but check a compatibility table if you must support very old ones.