Your Search Results

    Event

    Introduction

    This chapter describes the DOM Event Model. The Event interface itself is described, as well as the interfaces for event registration on nodes in the DOM, and event listeners, and several longer examples that show how the various event interfaces relate to one another.

    There is an excellent diagram that clearly explains the three phases of event flow through the DOM in the DOM Level 3 Events draft.

    Also see Example 5: Event Propagation in the Examples chapter for a more detailed example of how events move through the DOM.

    Registering event listeners

    There are 3 ways to register event handlers for a DOM element.

    EventTarget.addEventListener

    // Assuming myButton is a button element
    myButton.addEventListener('click', function(){alert('Hello world');}, false);
    

    This is the method you should use in modern web pages.

    Note: Internet Explorer 6-8 didn't support this method, offering a similar element.attachEvent API instead. For cross-browser compatibility use one of the many JavaScript libraries available.

    More details can be found on the EventTarget.addEventListener reference page.

    HTML attribute

    <button onclick="alert('Hello world!')">
    

    The JavaScript code in the attribute is passed the Event object via the event parameter. The return value is treated in a special way, described in the HTML specification.

    This way should be avoided. This makes the markup bigger and less readable. Concerns of content/structure and behavior are not well-separated, making a bug harder to find.

    DOM element properties

    // Assuming myButton is a button element
    myButton.onclick = function(event){alert('Hello world');};
    

    The function can be defined to take an event parameter. The return value is treated in a special way, described in the HTML specification.

    The problem with this method is that only one handler can be set per element and per event.

    DOM Event interface

    Event handlers may be attached to various objects including DOM elements, document, the window object, etc. When an event occurs, an event object is created and passed sequentially to the event listeners.

    The DOM Event interface is accessible from within the handler function, via the event object passed as the first argument. The following simple example shows how an event object is passed to the event handler function, and can be used from within one such function.

    function foo(evt) {
      // the evt parameter is automatically assigned the event object
      alert(evt);
    }
    table_el.onclick = foo;
    

    DOM event subclasses

    Properties

    event.bubbles
    A boolean indicating whether the event bubbles up through the DOM or not.
    event.cancelBubble
    A boolean indicating whether the bubbling of the event has been canceled or not.
    event.cancelable
    A boolean indicating whether the event is cancelable.
    event.currentTarget
    A reference to the currently registered target for the event.
    event.defaultPrevented
    Indicates whether or not event.preventDefault() has been called on the event.
    event.eventPhase
    Indicates which phase of the event flow is being processed.
    event.explicitOriginalTarget
    The explicit original target of the event (Mozilla-specific).
    event.originalTarget
    The original target of the event, before any retargetings (Mozilla-specific).
    event.target
    A reference to the target to which the event was originally dispatched.
    event.timeStamp
    The time that the event was created.
    event.type
    The name of the event (case-insensitive).
    event.isTrusted
    Indicates whether or not the event was initiated by the browser (after a user click for instance) or by a script (using an event creation method, like event.initEvent)

    Methods

    event.initEvent
    Initializes the value of an Event created through the DocumentEvent interface.
    event.preventBubble Obsolete since Gecko 24
    Prevents the event from bubbling. Obsolete, use event.stopPropagation instead.
    event.preventCapture Obsolete since Gecko 24
    Obsolete, use event.stopPropagation instead.
    event.preventDefault
    Cancels the event (if it is cancelable).
    event.stopImmediatePropagation
    For this particular event, no other listener will be called. Neither those attached on the same element, nor those attached on elements which will be traversed later (in capture phase, for instance)
    event.stopPropagation
    Stops the propagation of events further along in the DOM.

    See also