{"id":539,"date":"2018-04-18T14:00:17","date_gmt":"2018-04-18T14:00:17","guid":{"rendered":"https:\/\/www.audero.it\/blog\/?p=539"},"modified":"2025-05-04T22:16:14","modified_gmt":"2025-05-04T22:16:14","slug":"in-depth-guide-event-listeners","status":"publish","type":"post","link":"https:\/\/www.audero.it\/blog\/2018\/04\/18\/in-depth-guide-event-listeners\/","title":{"rendered":"An in-depth guide to event listeners"},"content":{"rendered":"

When creating interactive web pages, developers often need to execute some actions when a given event occurs. Changing the image of a carousel when a user clicks on one of its arrows, showing a tooltip when a word is hovered, or validating a field when a user moves the focus onto another field are common examples. To execute these actions, we have to add event listeners to the elements of the page.<\/p>\n

In this article, I’ll explain what event listeners are, and how to add and remove them from a web page. I’ll show several examples and talk about patterns to avoid when dealing with event listeners. The topic will be discussed in depth. So, even if you’re an expert, you might not know some of the details covered.
\n<\/p>\n

What is an event listener?<\/h2>\n

Before we delve into the discussion of adding and removing event listeners, let’s know more about them.<\/p>\n

W3C definition<\/h3>\n

According to the W3C<\/abbr>, an event listener<\/dfn><\/a> is an object that implements the EventListener<\/code> interface<\/a>, which defines a single method named handleEvent()<\/code>. An event listener is used to observe a specific event and perform one or more actions when it occurs. Event listeners are executed asynchronously via the event loop<\/a>, in the same order they are added.<\/p>\n

In older versions of Internet Explorer, the execution order wasn’t guaranteed to be the same as the order in which event listeners were added.<\/small><\/p>\n

The EventListener<\/code> interface is reported below:<\/p>\n

\ninterface EventListener {\n   void handleEvent(in Event evt);\n};\n<\/pre>\n
The handleEvent()<\/code> method defines only one parameter which is the event object, implementing the Event<\/code> interface<\/a>, representing the event triggered such as click<\/code> and focus<\/code>. The method returns nothing (undefined<\/code>, to be precise).<\/p>\n
In conclusion, an object that possesses a handleEvent()<\/code> method, like the one defined below, is a valid event listener.<\/p>\n
\nconst eventListener = {\n   handleEvent: function(event) {\n      \/\/ Do something here, possibly using the event parameter\n   }\n};\n<\/pre>\n
If you have ever added an event listener to an element in the past, the previous object will look weird. It isn’t what almost every developer employs or is accustomed to. Most developers have never used an object when adding an event listener, but only a function. The W3C specifications explain this case:<\/p>\n
Note: In JavaScript, user-defined functions are considered to implement the EventListener<\/code> interface. Thus the event object will be provided as the first parameter to the user-defined function when it is invoked.<\/p><\/blockquote>\n
Functions used as event listeners can be named or anonymous, and defined before their usage or inline. Some examples are shown below:<\/p>\n
\n\/\/ Named function\nfunction foo() {}\n\n\/\/ Anonymous function\nfunction() {}\n<\/pre>\n
Because every function is a valid event listener, methods can be used as well. The snippet below defines a Utility<\/code> object with a showTooltip()<\/code> method:<\/p>\n
\nconst Utility = {\n   showTooltip: function(event) {\n      \/\/ Do something here, possibly using the event parameter\n   }\n};\n<\/pre>\n
The difference between this example and the previous one where we saw an object is that we can only use the method as an event listener while in the other we can also use the object itself. So, the showTooltip()<\/code> method can be used as an event listener, while the Utility<\/code> object can’t. The reason is that the latter doesn’t possess a handleEvent()<\/code> method. If this distinction is not clear yet, we’ll see some examples of use of a function and an object as event listeners in the remainder of the article.<\/p>\n
WHATWG definition<\/h3>\n
The WHATWG DOM specifications<\/a> provide a different definition of event listener. According to the WHATWG<\/abbr>, an event listener<\/a> consists of a type, a callback (which can be either null<\/code> or that implements the EventListener<\/code> interface), and other fields like capture<\/code>, passive<\/code>, once<\/code>, and removed<\/code>. As we’ll examine in the upcoming sections, the different definitions won’t have any impact on us as developers.<\/p>\n
Now that we know what an event listener is, let’s see how to add one to an element of a web page.<\/p>\n
Adding event listeners<\/h2>\n
With event listeners we can create interactive web pages by running animations, injecting new elements in the page, or performing any other action we wish when a given event occurs.<\/p>\n
To add an event listener we have to employ the addEventListener()<\/code> method<\/a>. It allows the registration of an event listener on an event target<\/em> (an object that implements the EventTarget<\/code> interface<\/a>). Most elements of a web page are event targets (for example comments are not). window<\/code> and document<\/code> are event targets as well. Other objects that are event targets include XMLHttpRequest<\/code>, AudioNode<\/code>, and AudioContext<\/code>.<\/p>\n
addEventListener()<\/code> has two signatures:<\/p>\n
\naddEventListener(type, listener[, useCapture]);\naddEventListener(type, listener[, options]);\n<\/pre>\n
Different resources refer to the second parameter with different names. In addition to the terms event listener<\/em>, listener<\/em>, and function<\/em>, you can find the use of callback<\/em> (adopted by the WHATWG specifications<\/a>) or handler<\/em> (used by the addEventListener()<\/code>‘s page on MDN<\/abbr><\/a>).<\/small><\/p>\n
Both the signatures define three parameters, the last of which is optional. The first parameter, type<\/code>, is a string representing the event type<\/em> to listen (such as click<\/code> and focus<\/code>). listener<\/code> defines the object containing a handleEvent()<\/code> method or function that we wish to use as the event listener. The last parameter differs in the two signatures. useCapture<\/code> is a Boolean that indicates if we want the function to be executed during the capture phase<\/a> (true<\/code>) or the bubble phase<\/a> (false<\/code>). The default value for useCapture<\/code> is false<\/code>. The second signature has the options<\/code> parameter which is an object that describes how the event listener will behave.<\/p>\n
The third parameter hasn’t always been optional. That’s why in very old code you might see the value false<\/code> passed instead of relying on the default value.<\/small><\/p>\n
There are three properties that we can use at the moment for the options<\/code> parameter, but the list is likely to grow in future:<\/p>\n