You are here: Reference > JavaScript > client-side > event handling > methods > addEventListener

addEventListener method

Browser support:
9
Registers an event handler function (event listener) for the specified event on the current object.
Note: The addEventListener method is supported in Internet Explorer from version 9.
Event handlers can also be registered by inline event properties (e.g. obj.onclick = handler), but the addEventListener method provides various possibilities. Event properties are not supported for some events (e.g. DOMAttrModified, textInput, etc.) and the addEventListener method can be used for event capturing.
The third parameter of the addEventListener method specifies whether the registered event handler captures the specified event or not. If the event handler captures an event, then every time when the event occurs on the element or its descendants, the event handler will be called.
  1. When an event occurs, the event listeners that capture the event are called in the first phase (capturing phase).
  2. After this phase, the event will be dispatched to the original target element (target phase).
  3. Finally, if the event propagates up, then it will be dispatched to the ancestor elements of the original target element (bubbling phase).
Event propagation and capturing work differently in browsers. You can find a detailed description about them and some others (such as how to cancel an event) on the page for the event object.
The addEventListener method does not work in Internet Explorer before version 9. In earlier Internet Explorer versions, use the attachEvent method to register an event handler and the setCapture method for mouse capturing.
Use the removeEventListener method to remove an event listener that has been registered with the addEventListener method.

Syntax:

object.addEventListener (eventName, function, useCapture);
You can find the related objects in the Supported by objects section below.

Parameters:

eventName
Required. String that specifies the name of the event to listen for.
For a complete list of events, see the page for Events in JavaScript.
This parameter is case sensitive!
function
Required. Represents the event listener function to be called when the event occurs.
When an event occurs, an event object is initialized and passed to the event handler as the first parameter. The type of the event object depends on the current event.
useCapture
Required. Boolean that specifies whether the event needs to be captured or not.
One of the following values:
false
Register the event handler for the bubbling phase.
true
Register the event handler for the capturing phase.

Return value:

This method has no return value.

Example HTML code 1:

This example illustrates the use of the addEventListener and attachEvent methods:
<head>
    <script type="text/javascript">
        function OnButtonDown (button) {
            button.style.color = "#ff0000";
        }
        function OnButtonUp (button) {
            button.style.color = "#000000";
        }

        function Init () {
            var button = document.getElementById ("testButton");
            if (button.addEventListener) {  // all browsers except IE before version 9
                button.addEventListener ("mousedown", function () {OnButtonDown (button)}, false);
                button.addEventListener ("mouseup", function () {OnButtonUp (button)}, false);
            }
            else {
                if (button.attachEvent) {   // IE before version 9
                    button.attachEvent ("onmousedown", function () {OnButtonDown (button)});
                    button.attachEvent ("onmouseup", function () {OnButtonUp (button)});
                }
            }
        }
    </script>
</head>
<body onload="Init ()">
    Click on the following button and see its text color.
    <br />
    <button id="testButton">Test button</button>
</body>
Did you find this example helpful? yes no

Example HTML code 2:

This example illustrates the use of the addEventListener, attachEvent, removeEventListener and detachEvent methods:
<head>
    <script type="text/javascript">
        function OnRedClick () {
            alert ("A click event has occurred on the red button.");
        }

        function AddEventHandler () {
            var redButton = document.getElementById ("redButton");
            if (redButton.addEventListener) {   // all browsers except IE before version 9
                redButton.addEventListener ("click", OnRedClick, false);
            } 
            else {
                if (redButton.attachEvent) {    // IE before version 9
                    redButton.attachEvent ('onclick', OnRedClick);
                }
            }
        }

        function RemoveEventHandler () {
            var redButton = document.getElementById ("redButton");
            if (redButton.removeEventListener) {    // all browsers except IE before version 9
                redButton.removeEventListener ("click", OnRedClick, false);
            }
            else {
                if (redButton.detachEvent) {        // IE before version 9
                    redButton.detachEvent ('onclick', OnRedClick);
                }
            }
        }
    </script>
</head>
<body>
    Click on the red button when the 'click' event has a listener and when it does not.<br />
    <button onclick="AddEventHandler ();">Add a 'click' event listener to the red button</button>
    <button onclick="RemoveEventHandler ();">Remove the event listener</button>
    <br /><br />
    <button id="redButton" style="background-color:red">Red button</button>
</body>
Did you find this example helpful? yes no

Example HTML code 3:

This example illustrates a cross-browser solution for event capturing:
<head>
    <style>
        #square {
            position:absolute;
            left:200px;
            top:200px;
            width:20px;
            height:20px;
            background:red;
        }
    </style>
    <script type="text/javascript">
        var capturing = false;

        function ToggleCapture () {
            var square = document.getElementById ("square");
            if (capturing) {
                if (window.removeEventListener) {   // all browsers except IE before version 9
                    capturing = false;
                    window.removeEventListener ("mousemove", MoveSquare, true);
                }
                else {
                    if (square.releaseCapture) {    // IE before version 9
                        square.releaseCapture ();
                    }
                }
            }
            else {
                if (window.addEventListener) {  // all browsers except IE before version 9
                    capturing = true;
                    window.addEventListener ("mousemove", MoveSquare, true);
                }
                else {
                    if (square.setCapture) {    // IE before version 9
                        capturing = true;
                        square.setCapture ();
                    }
                }
            }
        }

        function OnLoseCapture () {
            capturing = false;
        }
        
        function MoveSquare (event) {
            if (capturing) {
                var square = document.getElementById ("square");
                square.style.left = event.clientX + "px";
                square.style.top = event.clientY + "px";
            }
        }
    </script>
</head>
<body onkeydown="ToggleCapture ();"> <br />
    <h3 style="text-align:center">Press any key to toggle capture!</h3>
    While mouse events are captured, the square follows the mouse.
    <div id="square" onmousemove="MoveSquare (event);" onlosecapture="OnLoseCapture ()"></div>
</body>
Did you find this example helpful? yes no

Example HTML code 4:

This example shows how to detect when the user presses a mouse button over an element but releases the button outside the element:
<head>
    <script type="text/javascript">
        var capturedButton = null;
        function OnButtonDown (button) {
            capturedButton = button;
            if (window.addEventListener) {  // all browsers except IE before version 9
                window.addEventListener ("mouseup", OnButtonUp, true);
            }
            else {
                if (button.setCapture) {    // IE before version 9
                    button.attachEvent ("onlosecapture", OnButtonLoseCapture);
                    button.setCapture ();
                }
            }
        }
        function OnButtonUp () {
            if (capturedButton) {
                if (window.removeEventListener) {   // all browsers except IE before version 9
                    window.removeEventListener ("mouseup", OnButtonUp, true);
                }
                else {
                    if (capturedButton.releaseCapture) {    // IE before version 9
                        capturedButton.detachEvent ("onlosecapture", OnButtonLoseCapture);
                        capturedButton.releaseCapture ();
                    }
                }
                capturedButton = null;
            }
            alert ("The button has been released!");

        }

        function OnButtonLoseCapture () {
            alert ("The button loses the mouse capture!");
            OnButtonUp ();
        }

        function Init () {
            var button = document.getElementById ("testButton");
            if (button.addEventListener) {  // all browsers except IE before version 9
                button.addEventListener ("mousedown", function () {OnButtonDown (button)}, false);
            }
            else {
                if (button.attachEvent) {   // IE before version 9
                    button.attachEvent ("onmousedown", function () {OnButtonDown (button)});
                    button.attachEvent ("onmouseup", OnButtonUp);
                }
            }
        }
    </script>
</head>
<body onload="Init ()">
    Press the following button and release the mouse button somewhere inside or outside the browser.
    <br />
    <button id="testButton">Capture Test</button>
</body>
Did you find this example helpful? yes no

Example HTML code 5:

This example implements a simple spin control:
<head>
    <script type="text/javascript">
        var capturedButton = null;
        var changeTimer = 0;

        function ChangeInput (increase, delay) {
            var myInput = document.getElementById ("myInput");
                // parse the current value
            var value = Number (myInput.value);
            if (isNaN (value)) {
                value = 0;
            }
                // direction
            var dir = increase ? 1 : -1;
                // the new value
            var step = 1;
            value += dir * step;
            if (value < 0) {
                value = 0;
            }
            if (value > 100) {
                value = 100;
            }
            myInput.value = value;

            changeTimer = setTimeout (function () {ChangeInput (increase, 100)}, delay);
        }

        function OnButtonDown (button, increase) {
                // capture mouse up
            capturedButton = button;
            if (window.addEventListener) {  // all browsers except IE before version 9
                window.addEventListener ("mouseup", OnButtonUp, true);
            }
            else {
                if (button.setCapture) {    // IE before version 9
                    button.attachEvent ("onlosecapture", OnButtonLoseCapture);
                    button.setCapture ();
                }
            }

                // initialy a longer delay
            ChangeInput (increase, 500);
        }
        
        function OnButtonUp () {
            if (changeTimer) {
                clearTimeout (changeTimer);
                changeTimer = 0;
            }

            if (capturedButton) {
                if (window.removeEventListener) {   // all browsers except IE before version 9
                    window.removeEventListener ("mouseup", OnButtonUp, true);
                }
                else {
                    if (capturedButton.releaseCapture) {    // IE before version 9
                        capturedButton.detachEvent ("onlosecapture", OnButtonLoseCapture);
                        capturedButton.releaseCapture ();
                    }
                }
                capturedButton = null;
            }
        }

        function OnButtonLoseCapture () {
            OnButtonUp ();
        }

        function Init () {
            var incButton = document.getElementById ("incButton");
            var decButton = document.getElementById ("decButton");
            if (incButton.addEventListener) {   // all browsers except IE before version 9
                incButton.addEventListener ("mousedown", function () {OnButtonDown (incButton, true)}, false);
                decButton.addEventListener ("mousedown", function () {OnButtonDown (decButton, false)}, false);
            }
            else {
                if (incButton.attachEvent) {    // IE before version 9
                    incButton.attachEvent ("onmousedown", function () {OnButtonDown (incButton, true)});
                    decButton.attachEvent ("onmousedown", function () {OnButtonDown (decButton, false)});
                    incButton.attachEvent ("onmouseup", OnButtonUp);
                    decButton.attachEvent ("onmouseup", OnButtonUp);
                }
            }
        }
    </script>
</head>
<body onload="Init ()">
    <input id="myInput" size="3" value="50" />
    <button id="incButton">Increase</button>
    <button id="decButton">Decrease</button>
</body>
Did you find this example helpful? yes no

Supported by objects:

Related pages:

External links:

User Contributed Comments

Post Content

Post Content