EventTarget.addEventListener()

The EventTarget.addEventListener() method registers the specified listener on the EventTarget it’s called on. 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

JavaScript

Copy Code

target.addEventListener(type, listener[, options]);
target.addEventListener(type, listener[, useCapture]);
target.addEventListener(type, listener[, useCapture, wantsUntrusted <span title=
"
This API has not been standardized."
>class=
"
icon-warning-sign"
> 
</
span
>
]); 

Parameters

type

A string representing the event type to listen for.

listener

The object that receives a notification (an object that implements the Event interface) when an event of the specified type occurs. This must be an object implementing the EventListener interface, or simply a JavaScript function.

options

Optional

An options object that specifies characteristics about the event listener. The available options are:

• capture: A Boolean that indicates that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree.  
• once: A Boolean indicating that the listener should be invoked at most once after being added. If it is true, the listener would be removed automatically when it is invoked.
• passive: A Boolean indicating that the listener will never call preventDefault(). If it does, the user agent should ignore it and generate a console warning.

• mozSystemGroup: Available only in code running in XBL or in Firefox’ chrome, it is a Boolean defining if the listener is added to the system group.

useCapture

Optional

A Boolean that indicates that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget 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 that 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 to false.

Note: For event listeners attached to the event target; the event is in the target phase, rather than capturing and bubbling phases. Events in the target phase will trigger all listeners on an element regardless of the useCapture parameter.

Note: useCapture became optional only in more recent versions of the major browsers; for example, it was not optional before Firefox 6. You should provide this parameter for broadest compatibility.

wantsUntrusted

If true, the listener receives synthetic events dispatched by web content (the default is false for chrome and true for regular web pages). This parameter is only available in Gecko and is mainly useful for the code in add-ons and the browser itself. See Interaction between privileged and non-privileged pages for an example.

Example

Add a simple listener

HTML Content

HTML

Copy Code

<
table
 
id
="
outside"
>
    
<
tr
>
<
td
 
id
="
t1"
>
one
<
/td
>
<
/tr
>
    
<
tr
>
<
td
 
id
="
t2"
>
two
<
/td
>
<
/tr
>
<
/table
>

JavaScript Content

JavaScript

Copy Code

 
function
 modifyText() {
  
var
 t2 = 
document
.getElementById(
"
t2"
);
  
if
 (t2.firstChild.nodeValue == 
"
three"
) {
    t2.firstChild.nodeValue = 
"
two"
;
  } 
else
 {
    t2.firstChild.nodeValue = 
"
three"
;
  }
}

 
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 run modifyText().

If you want to pass parameters to the listener function, you may use an anonymous function.

Event Listener with anonymous function

HTML Content

HTML

Copy Code

<
table
 
id
="
outside"
>
    
<
tr
>
<
td
 
id
="
t1"
>
one
<
/td
>
<
/tr
>
    
<
tr
>
<
td
 
id
="
t2"
>
two
<
/td
>
<
/tr
>
<
/table
>

JavaScript Content

JavaScript

Copy Code

 
function
 modifyText(new_text) {
  
var
 t2 = 
document
.getElementById(
"
t2"
);
  t2.firstChild.nodeValue = new_text;    
}
 
 
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. Its 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 gets 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 EventListeners 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.

When 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 (e.g., onclick) is specified on an element in the HTML source, the JavaScript code in the attribute value is effectively wrapped in a handler function that binds the value of this in a manner consistent with the use of 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. Therefore, given the following example:

HTML

Copy Code

<
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)

Note: JavaScript 1.8.5 introduces the 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 later remove it.

JavaScript 1.8.5 introduces themethod, which lets you specify the value that should be used asfor 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 later remove it.

This is an example with and without bind:

JavaScript

Copy Code

var
 Something = 
function
(element) {
   
  
this
.name = 
'
Something Good'
;
  
this
.onclick1 = 
function
(event) {
    
console
.log(
this
.name);  
  };
  
this
.onclick2 = 
function
(event) {
    
console
.log(
this
.name);  
  };
  element.addEventListener(
'
click'
, 
this
.onclick1, 
false
);
  element.addEventListener(
'
click'
, 
this
.onclick2.bind(
this
), 
false
);  
}
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:

JavaScript

Copy Code

var
 Something = 
function
(element) {
   
  
this
.name = 
'
Something Good'
;
  
this
.handleEvent = 
function
(event) {
    
console
.log(
this
.name);  
    
switch
(event.type) {
      
case
 
'
click'
:
         
        
break
;
      
case
 
'
dblclick'
:
         
        
break
;
    }
  };

   
  element.addEventListener(
'
click'
, 
this
, 
false
);
  element.addEventListener(
'
dblclick'
, 
this
, 
false
);

   
  element.removeEventListener(
'
click'
, 
this
, 
false
);
  element.removeEventListener(
'
dblclick'
, 
this
, 
false
);
}
var
 s = 
new
 Something(
document
.body);

Legacy Internet Explorer and attachEvent

In Internet Explorer versions before IE 9, you have to use attachEvent rather than the standard addEventListener. For IE, modify the preceding example to:

JavaScript

Copy Code

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 the addEventListener, removeEventListener, Event.preventDefault and Event.stopPropagation not being supported by IE 8 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 of it. Please also note that the following code only adds support to IE 8.

Also note that this IE8 polyfill ONLY works in standards mode: a doctype declaration is required.

JavaScript

Copy Code

(
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  ) {
      
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  ) {
      
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:

JavaScript

Copy Code

 
el.onclick = modifyText;

 
element.onclick = 
function
() {
   
};

This method replaces the existing click event listener(s) on the element if there are any. Similarly for other events and associated event handlers such as blur (onblur), keypress (onkeypress), and so on.

Because it was essentially part of DOM 0, this method is very widely supported and requires no special cross–browser code; hence it is normally used to register event listeners dynamically unless the extra features of addEventListener() are needed.

Memory issues

JavaScript

Copy Code

var
 i;
var
 els = 
document
.getElementsByTagName(
'
*'
);

 
for
(i=
0
 ; i<els.length ; i++){
  els[i].addEventListener(
"
click"
, 
function
(e){ }, 
false
);
}

 
function
 processEvent(e){
   
}

for
(i=
0
 ; i<els.length ; i++){
  els[i].addEventListener(
"
click"
, processEvent, 
false
);
}

In the first case, a new (anonymous) function is created at each loop turn. 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, since no reference to the anonymous functions is kept, it is not possible to call element.removeEventListener because we do not have a reference to the handler, while, in the second case, it’s possible to do myElement.removeEventListener("click", processEvent, false).

Improving scrolling performance with passive listeners

JavaScript

Copy Code

var
 elem = 
document
.getElementById(
'
elem'
);
elem.addEventListener(
'
<code>touchmove</code>'
, 
function
 listener() {
   
}, { passive: 
true
 });

This way a touchmove listener will not block while a user is scrolling (same applies to wheel events). Demo available here (Google Developers Page).

Beware: Browsers who do not support event listener options will see the 3rd argument as useCapture and therefore as true.

 

Specifications

Browser compatibility

Feature
Chrome
Firefox (Gecko)
Internet Explorer
Opera
Safari (WebKit)

Basic support
1.0[1][2]
1.0 (1.7 or earlier)[3]
9.0[4]
7
1.0[1]

useCapture made optional
1.0
6 (6)
9.0
11.60

(Yes)

options parameter (with capture and passive values)[5]

49.0 (capture) 51.0 (passive)

49 (49)

No support

No support

Landed in Nightly WebKit bug 158601
once value in the options parameter
55
50 (50)

No support

No support

Landed in Nightly WebKit bug 149466

Feature
Android
Android Webview
Firefox Mobile (Gecko)
IE Mobile
Opera Mobile
Safari Mobile
Chrome for Android

Basic support
1.0

(Yes)[2]

1.0 (1.0)[3]
9.0
6.0
1.0[1]

(Yes)[2]

useCapture made optional

?

(Yes)

6.0 (6)

?

?

?

(Yes)

options parameter (with capture and passive values)[5]

No support

49.0 (capture) 51.0 (passive)
49.0 (49)

?

?

?

49.0 (capture) 51.0 (passive)

once value in the options parameter

No support

No support

50 (50)

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] Prior to Firefox 6, the browser would throw an error if the useCapture parameter was not explicitly false. Prior to 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 backwards compatibility, browsers that support options allow the third parameter to be either options or Boolean.

See also

License

© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/eventtarget/addeventlistener