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.
target.addEventListener(type, listener); target.addEventListener(type, listener, options);
Try it
Syntax
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
TypeErroris thrown iflisteneris neither a function, an object, nornull, or if fewer than two arguments are passed.
Usage notes
- Duplicates are ignored. If you add the same function with the same
typeand the samecapturevalue 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 samecapturevalue. An inline arrow function cannot be removed later unless you stored it in a variable, or you used thesignaloronceoption. thisin the listener. In a regularfunction,thisis the element the listener was added to (the same asevent.currentTarget). In an arrow function,thisis whatever it was in the surrounding code, so useevent.currentTargetthere.passive: trueand scrolling. Fortouchstart,touchmoveandwheellisteners onwindow,documentanddocument.body, browsers treat the listener as passive by default. A passive listener that callspreventDefault()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 toelement.onclickallows only one handler, and a later assignment replaces the earlier one. - Cleaning up many listeners. Pass the same
AbortControllersignal to every listener you add and callcontroller.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.
Related
EventTarget.removeEventListener()โ remove a listenerEventTarget.dispatchEvent()โ fire an event yourself- event bubbling and capturing โ what the
captureoption changes - the
onceandsignaloptions โ listener options in detail - passive listeners โ the
passiveoption - Lesson: Events
- Lesson: Event delegation