The EventTarget.addEventListener()
method adds the specified EventListener
-compatible object to the list of event listeners for the specified event type on the EventTarget
on which it is called. The event target may be an Element
in a document, the Document
itself, a Window
, or any other object that supports events (such as XMLHttpRequest
).
Syntax
target.addEventListener(type, listener[, options]);
target.addEventListener(type, listener[, useCapture]);
target.addEventListener(type, listener[, useCapture, wantsUntrusted ]); // Gecko/Mozilla only
Parameters
type
- A string representing the event type to listen for.
listener
- The object which receives a notification (an object that implements the
Event
interface) when an event of the specified type occurs. This must be an object implementing theEventListener
interface, or a JavaScript function. options
Optional- An options object that specifies characteristics about the event listener. The available options are:
capture
: ABoolean
indicating that events of this type will be dispatched to the registeredlistener
before being dispatched to anyEventTarget
beneath it in the DOM tree.once
: ABoolean
indicating that thelistener
should be invoked at most once after being added. Iftrue
, thelistener
would be automatically removed when invoked.passive
: ABoolean
indicating that thelistener
will never callpreventDefault()
. If it does, the user agent should ignore it and generate a console warning. See Improving scrolling performance with passive listeners to learn more.-
mozSystemGroup
: ABoolean
indicating that the listener should be added to the system group. Available only in code running in XBL or in Firefox's chrome.
useCapture
Optional- A
Boolean
indicating that events of this type will be dispatched to the registeredlistener
before being dispatched to anyEventTarget
beneath it in the DOM tree. Events that are bubbling upward through the tree will not trigger a listener designated to use capture. Event bubbling and capturing are two ways of propagating events which occur in an element that is nested within another element, when both elements have registered a handle for that event. The event propagation mode determines the order in which elements receive the event. See DOM Level 3 Events and JavaScript Event order for a detailed explanation. If not specified,useCapture
defaults tofalse
. -
Note: For event listeners attached to the event target, the event is in the target phase, rather than the capturing and bubbling phases. Events in the target phase will trigger all listeners on an element in the order they were registered, regardless of the
useCapture
parameter.Note:useCapture
has not always been optional. Ideally, you should include it for the widest possible browser compatibility. wantsUntrusted
- A Firefox (Gecko)-specific parameter. If
true
, the listener receives synthetic events dispatched by web content (the default isfalse
for chrome andtrue
for regular web pages). This parameter is useful for code found in add-ons as well as the browser itself. See Interaction between privileged and non-privileged pages for an example.
Before using a particular value in the options
object, it's a good idea to ensure that the user's browser supports it, since these are an addition that not all browsers have supported historically. See Safely detecting option support for details.
Safely detecting option support
In older versions of the DOM specification, the third parameter of addEventListener()
was a Boolean value indicating whether or not to use capture. Over time, it became clear that more options were needed. Rather than adding more parameters to the function (complicating things enormously when dealing with optional values), the third parameter was changed to an object which can contain various properties defining the values of options to configure the process of removing the event listener.
Because older browsers (as well as some not-too-old browsers) still assume the third parameter is a Boolean, you need to build your code to handle this scenario intelligently. You can do this by using feature detection for each of the options you're interested in.
For example, if you want to check for the passive
option:
var passiveSupported = false; try { var options = Object.defineProperty({}, "passive", { get: function() { passiveSupported = true; } }); window.addEventListener("test", null, options); } catch(err) {}
This creates an options
object with a getter function for the passive
property; the getter sets a flag, passiveSupported
, to true
if it gets called. That means that if the browser checks the value of the passive
property on the options
object, passiveSupported
will be set to true
; otherwise, it will remain false
. We then call addEventListener()
to set up a fake event handler, specifying those options, so that the options will be checked if the browser recognizes an object as the third parameter.
You can check whether any option is supported this way. Just add a getter for that option using code similar to what is shown above.
Then, when you want to create an actual event listener that uses the options in question, you can do something like this:
someElement.addEventListener("mouseup", handleMouseUp, passiveSupported ? { passive: true } : false);
Here, we're adding a listener for the mouseup
event on the element someElement
. For the third parameter, if passiveSupported
is true
, we're specifying an options
object with passive
set to true
; otherwise, we know that we need to pass a Boolean, and we pass false
as the value of the useCapture
parameter.
If you'd prefer, you can use a third-party library like Modernizr or Detect It to do this test for you.
You can learn more from the article about EventListenerOptions
from the Web Incubator Community Group.
Example
Add a simple listener
HTML
<table id="outside"> <tr><td id="t1">one</td></tr> <tr><td id="t2">two</td></tr> </table>
JavaScript
// Function to change the content of t2 function modifyText() { var t2 = document.getElementById("t2"); if (t2.firstChild.nodeValue == "three") { t2.firstChild.nodeValue = "two"; } else { t2.firstChild.nodeValue = "three"; } } // add event listener to table var el = document.getElementById("outside"); el.addEventListener("click", modifyText, false);
In the above example, modifyText()
is a listener for click
events registered using addEventListener()
. A click anywhere in the table bubbles up to the handler and runs modifyText()
.
If you want to pass parameters to the listener function, you may use an anonymous function.
Event listener with anonymous function
HTML
<table id="outside"> <tr><td id="t1">one</td></tr> <tr><td id="t2">two</td></tr> </table>
JavaScript
// Function to change the content of t2 function modifyText(new_text) { var t2 = document.getElementById("t2"); t2.firstChild.nodeValue = new_text; } // Function to add event listener to table var el = document.getElementById("outside"); el.addEventListener("click", function(){modifyText("four")}, false);
Notes
Why use addEventListener
?
addEventListener
is the way to register an event listener as specified in W3C DOM. The benefits are as follows:
- It allows adding more than a single handler for an event. This is particularly useful for DHTML libraries or Mozilla extensions that need to work well with other libraries/extensions.
- It gives you finer-grained control of the phase when the listener is activated (capturing vs. bubbling).
- It works on any DOM element, not just HTML elements.
The alternative, older way to register event listeners, is described below.
Adding a listener during event dispatch
If an EventListener
is added to an EventTarget
while it is processing an event, that event does not trigger the listener. However, that same listener may be triggered during a later stage of event flow, such as the bubbling phase.
Multiple identical event listeners
If multiple identical EventListener
s are registered on the same EventTarget
with the same parameters, the duplicate instances are discarded. They do not cause the EventListener
to be called twice, and they do not need to be removed manually with the removeEventListener method.
The value of this
within the handler
It is often desirable to reference the element on which the event handler was fired, such as when using a generic handler for a set of similar elements.
If attaching a handler function to an element using addEventListener()
, the value of this
inside the handler is a reference to the element. It is the same as the value of the currentTarget
property of the event argument that is passed to the handler.
If an event attribute (for example, onclick
) is specified on an element in the HTML source, the JavaScript code in the attribute value is effectively wrapped in a handler function which binds the value of this
in a manner consistent with the addEventListener()
; an occurrence of this
within the code represents a reference to the element. Note that the value of this
inside a function, called by the code in the attribute value, behaves as per standard rules. This is shown in the following example:
<table id="t" onclick="modifyText();"> . . .
The value of this
within modifyText(),
when called via the onclick
event, is a reference to the global (window
) object (or undefined
in the case of strict mode).
Function.prototype.bind()
method, which lets you specify the value that should be used as this
for all calls to a given function. This method lets you easily bypass problems where it's unclear what this will be, depending on the context from which your function was called. Note, however, that you'll need to keep a reference to the listener around so you can remove it later.This is an example with and without bind
:
var Something = function(element) { // |this| is a newly created object this.name = 'Something Good'; this.onclick1 = function(event) { console.log(this.name); // undefined, as |this| is the element }; this.onclick2 = function(event) { console.log(this.name); // 'Something Good', as |this| is bound to newly created object }; element.addEventListener('click', this.onclick1, false); element.addEventListener('click', this.onclick2.bind(this), false); // Trick } var s = new Something(document.body);
A problem in the example above is that you cannot remove the listener with bind
. Another solution is using a special function called handleEvent
to catch any events:
var Something = function(element) { // |this| is a newly created object this.name = 'Something Good'; this.handleEvent = function(event) { console.log(this.name); // 'Something Good', as this is bound to newly created object switch(event.type) { case 'click': // some code here... break; case 'dblclick': // some code here... break; } }; // Note that the listeners in this case are |this|, not this.handleEvent element.addEventListener('click', this, false); element.addEventListener('dblclick', this, false); // You can properly remove the listeners element.removeEventListener('click', this, false); element.removeEventListener('dblclick', this, false); } var s = new Something(document.body);
Another way of handling the reference to this is to pass to the EventListener a function that calls the method of the object which contains the fields that need to be accessed:
class SomeClass { constructor() { this.name = 'Something Good'; } register() { var that = this; window.addEventListener('keydown', function(e) {return that.someMethod(e);}); } someMethod(e) { console.log(this.name); switch(e.keyCode) { case 5: // some code here... break; case 6: // some code here... break; } } } var myObject = new SomeClass(); myObject.register();
Legacy Internet Explorer and attachEvent
In Internet Explorer versions before IE 9, you have to use attachEvent
, rather than the standard addEventListener
. For IE, we modify the preceding example to:
if (el.addEventListener) { el.addEventListener('click', modifyText, false); } else if (el.attachEvent) { el.attachEvent('onclick', modifyText); }
There is a drawback to attachEvent:
The value of this
will be a reference to the window
object, instead of the element on which it was fired.
Compatibility
You can work around addEventListener()
, removeEventListener()
, Event.preventDefault(),
and Event.stopPropagation()
not being supported by IE 8 by using the following code at the beginning of your script. The code supports the use of handleEvent
and also the DOMContentLoaded
event.
Note: useCapture is not supported, as IE 8 does not have any alternative method. The following code only adds IE 8 support. This IE 8 polyfill only works in standards mode: a doctype declaration is required.
(function() { if (!Event.prototype.preventDefault) { Event.prototype.preventDefault=function() { this.returnValue=false; }; } if (!Event.prototype.stopPropagation) { Event.prototype.stopPropagation=function() { this.cancelBubble=true; }; } if (!Element.prototype.addEventListener) { var eventListeners=[]; var addEventListener=function(type,listener /*, useCapture (will be ignored) */) { var self=this; var wrapper=function(e) { e.target=e.srcElement; e.currentTarget=self; if (typeof listener.handleEvent != 'undefined') { listener.handleEvent(e); } else { listener.call(self,e); } }; if (type=="DOMContentLoaded") { var wrapper2=function(e) { if (document.readyState=="complete") { wrapper(e); } }; document.attachEvent("onreadystatechange",wrapper2); eventListeners.push({object:this,type:type,listener:listener,wrapper:wrapper2}); if (document.readyState=="complete") { var e=new Event(); e.srcElement=window; wrapper2(e); } } else { this.attachEvent("on"+type,wrapper); eventListeners.push({object:this,type:type,listener:listener,wrapper:wrapper}); } }; var removeEventListener=function(type,listener /*, useCapture (will be ignored) */) { var counter=0; while (counter<eventListeners.length) { var eventListener=eventListeners[counter]; if (eventListener.object==this && eventListener.type==type && eventListener.listener==listener) { if (type=="DOMContentLoaded") { this.detachEvent("onreadystatechange",eventListener.wrapper); } else { this.detachEvent("on"+type,eventListener.wrapper); } eventListeners.splice(counter, 1); break; } ++counter; } }; Element.prototype.addEventListener=addEventListener; Element.prototype.removeEventListener=removeEventListener; if (HTMLDocument) { HTMLDocument.prototype.addEventListener=addEventListener; HTMLDocument.prototype.removeEventListener=removeEventListener; } if (Window) { Window.prototype.addEventListener=addEventListener; Window.prototype.removeEventListener=removeEventListener; } } })();
Older way to register event listeners
addEventListener()
was introduced with the DOM 2 Events specification. Before then, event listeners were registered as follows:
// Passing a function reference — do not add '()' after it, which would call the function! el.onclick = modifyText; // Using a function expression element.onclick = function() { // ... function logic ... };
This method replaces the existing click
event listener(s) on the element if there are any. Other events and associated event handlers such as blur
(onblur
) and keypress
(onkeypress
) behave similarly.
Because it was essentially part of DOM 0, this technique for adding event listeners is very widely supported and requires no special cross–browser code. It is normally used to register event listeners dynamically unless the extra features of addEventListener()
are needed.
Memory issues
var i; var els = document.getElementsByTagName('*'); // Case 1 for(i=0 ; i<els.length ; i++){ els[i].addEventListener("click", function(e){/*do something*/}, false); } // Case 2 function processEvent(e){ /*do something*/ } for(i=0 ; i<els.length ; i++){ els[i].addEventListener("click", processEvent, false); }
In the first case, a new (anonymous) function is created with each iteration of the loop. In the second case, the same previously declared function is used as an event handler. This results in smaller memory consumption. Moreover, in the first case, it is not possible to call removeEventListener()
because no reference to the anonymous function is kept. In the second case, it's possible to do myElement.removeEventListener("click", processEvent, false)
.
Improving scrolling performance with passive listeners
The default value for the passive option is false
. Starting in Chrome 56 (desktop, Chrome for Android, and Android webview) the default value for touchstart
and touchmove
is true
and calls to preventDefault()
are not permitted. To override this behavior, you set the passive
option to false
as shown in the example below. This change prevents the listener from blocking page rendering while a user is scrolling. A demo is available on the Google Developer site. Please note that Edge does not support the options
argument at all, and adding it will prevent the use of the useCapture
argument.
var elem = document.getElementById('elem');
elem.addEventListener('touchmove
', function listener() {
/* do something */
}, { passive: false });
Setting passive
isn't important for the basic scroll
event, as it cannot be canceled, so its listener can't block page rendering anyway.
Specifications
Specification | Status | Comment |
---|---|---|
DOM The definition of 'EventTarget.addEventListener()' in that specification. |
Living Standard | |
DOM4 The definition of 'EventTarget.addEventListener()' in that specification. |
Obsolete | |
Document Object Model (DOM) Level 2 Events Specification The definition of 'EventTarget.addEventListener()' in that specification. |
Obsolete | Initial definition |
Browser compatibility
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | 1.0[1][2] | (Yes) | 1.0 (1.7 or earlier)[3] | 9.0[4] | 7 | 1.0[1] |
useCapture made optional |
1.0 | (Yes) | 6 (6) | 9.0 | 11.60 | (Yes) |
options parameter (with capture and passive values)[5] |
49.0 ( |
No support | 49 (49) | No support | (Yes) | Landed in Nightly WebKit bug 158601 |
once value in the options parameter |
55 | No support | 50 (50) | No support | 42 | Landed in Nightly WebKit bug 149466 |
Passive defaults to true for touchstart and touchend |
55 | No support | No support | No support | No support | No support |
Feature | Android Webview | Chrome for Android | Edge | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|---|
Basic support |
(Yes)[2] |
(Yes) |
(Yes) | 1.0 (1.0)[3] | 9.0 | 6.0 | 1.0[1] |
useCapture made optional |
(Yes) |
(Yes) |
(Yes) | 6.0 (6) | ? | ? | ? |
options parameter (with capture and passive values)[5] |
49.0 (capture ) 51.0 (passive ) |
49.0 (capture ) 51.0 (passive ) |
No support | 49.0 (49) | ? | (Yes) | ? |
once value in the options parameter |
55 | 55 | No support | 50 (50) | No support | 42 | ? |
Passive defaults to true for touchstart and touchend |
55 | 55 | No support | No support | No support | No support | No support |
[1] Although WebKit has explicitly added [optional]
to the useCapture
parameter as recently as June 2011, it had been working before the change. The new change landed in Safari 5.1 and Chrome 13.
[2] Before Chrome 49, the type and listener parameters were optional.
[3] Before Firefox 6, the browser would throw an error if the useCapture
parameter was not explicitly false
. Before Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6), addEventListener()
would throw an exception if the listener
parameter was null
; now the method returns without error, but without doing anything.
[4] Older versions of Internet Explorer support the proprietary EventTarget.attachEvent
method instead.
[5] For backward compatibility, browsers that support options
allow the third parameter to be either options
or Boolean
.