DOM Events

  • Revision slug: DOM_Client_Object_Cross-Reference/DOM_Events
  • Revision title: DOM Events
  • Revision id: 40805
  • Created:
  • Creator: BYK
  • Is current revision? No
  • Comment 6 words removed

Revision Content

Overview

Events are things that happen to DOM elements in your page, such as mouse clicks or errors when an image fails to load.  When an event happens, the browser sends the event to the related element. If you've set a handler (a function) on that element, it gets called with related event info which means you "handled" the event.

More specifically, the event is sent to the element it happened in, plus all the elements that enclose it.  For instance, say you had a {{ HTMLElement("div") }} you wanted to act like a button:

<div onclick="getACupcake()">
  I <strong>Really</strong> want a cupcake!
</div>

If someone clicks on the word Really, first the event is delivered to the {{ HTMLElement("strong") }}.  That has no handler, so it's delivered to the {{ HTMLElement("div") }}.  That handler can, if it wants, let outer elements try to handle the event, too, or it can cancel it.

In fact, the event traverses twice; first it travels from the window down to the target element (called capture) and then it travels back up to the window again (called bubbling).  And, there are two ways to set a handler: capture and bubble.  For instance, capture can allow a big element to intercept all clicks to its child elements, before they get it.  Unfortunately, Internet Explorer doesn't implement capture, so it's effectively unavailable for many web authors.  

Handlers

When a handler gets called, it gets an {{ domxref("Event") }} object as its first argument, which has lots of fields that describe about the event, such as which keystroke was hit, what the mouse coordinates were, the time at which the event happened, etc.  Only Internet Explorer versions lower than 9 uses the global window.event object instead of an argument.  There are many ways to set an event handler, each with its own quirks.  More info here.

Inline

<div onclick='getACupcake(event)'>

This first way is often the easiest; this just executes the specified JavaScript code. It makes a wrapper routine that gets your code snippet spliced into it.  A trailing semicolon is optional. You can stick huge amounts of code in there but watch your embedded quotes and backslash them if they're the same type.

With the {{ domxref("Event") }} object, IE works differently from other browsers.  In IE, the event global has the event object.  In Firefox and other browsers, the event is passed in as an argument to the wrapper named event.  If you do it like the above, you'll never know the difference.  Flash: I think IE7 and IE8 now also pass in the event handler.

This method of assigning events are highly discouraged since it goes against the seperation of content and the code, creates problems when multiple event handlers are to be used and may even create security holes in your web applications so beware.

addEventListener()

The classy way to set a handler is to use addEventListener() on the target.

document.getElementById('cupcakeButton').addEventListener('click', getACupcake);

If you use this way, you can actually add multiple handlers for the same event on the same target.  You then can remove them if you need to with removeEventListener().

Unfortunately, IE works differently from other browsers.  There is no addEventListener() function and there is an attachEvent() function instead. It is used like below:

document.getElementById('cupcakeButton').attachEvent('onclick', getACupcake); 
Note: Internet Explorer 9 adds support for <code>addEventListener()</code>.

Assigning to event handler properties

The old way is to just assign it like this:

document.getElementById('cupcakeButton').onclick = getACupcake;

As above, the event object is either a global or an argument.  This method may have problems and is not the preferred method, but it still works and a lot of people still use it. Also Dean Edwards presents a cool usage of this method with cross-browser support for multiple event listeners.

Event object

The {{ domxref("Event") }} object your handler gets has more than a dozen properties.  Again, IE tends to be different on several areas.  In fact, when it comes to keystrokes, and wheel events, they're all different because the W3C didn't define the standard until years later.  

event.target is the original element the event happened to.  However, Internet Explorer calls it event.srcElement.  In fact, Chrome and Safari started setting both.  You can do this for maximum compatibility:

function getACupcake(event) {
  var target = event.target || event.srcElement;
  target.style.backgroundColor = '#F00';  // use it
}

 Check out the Quirks Mode site for more info about browser differences.

Events

Event W3C DOM Level 3{{ Ref("w3c-dom") }} Gecko DOM (FF2){{ Ref("gecko-dom") }} MSHTML DOM (IE){{ Ref("mshtml-dom") }} Cancel Value ({{ mediawiki.external('X') }}HTML)
Bubbles Cancelable Bubbles Cancelable Bubbles Cancelable
User interface event types
DOMActivate yes yes yes ? yes(?) no(?) ?
DOMFocusIn yes no yes ? - -  
DOMFocusOut yes no yes ? - -  
blur no no no ? no no  
focus no no no ? no no  
Text event types
textInput yes yes ? ? - - ?
Mouse event types
click yes yes yes yes yes yes false
mousedown yes yes yes ? yes yes ?
mousemove yes yes yes ? yes no ?
mouseover yes yes yes yes yes yes true
mouseout yes yes yes yes yes no true
mouseup yes yes yes ? yes yes ?
Keyboard event types
keydown yes yes yes yes yes yes false
keyup yes yes yes yes yes no false
keypress (proprietary, see textInput) - - yes yes yes yes false
Mutation and mutation name event types
DOMSubtreeModified yes no yes ? - -  
DOMNodeInserted yes no yes ? - -  
DOMNodeRemoved yes no yes ? - -  
DOMNodeRemovedFromDocument yes no yes ? - -  
DOMNodeInsertedIntoDocument yes no yes ? - -  
DOMAttrModified yes no yes ? - -  
DOMCharacterDataModified yes no yes ? - -  
DOMElementNameChanged yes no yes ? - -  
DOMAttributeNameChanged yes no yes ? - -  
Basic event types
abort yes no yes ? no yes  
beforeunload - - no ? no yes  Any string
change yes no yes ? no yes  
error yes no no yes no yes true
load no no no ? no no  
reset yes yes yes ? no yes ?
resize yes no yes ? no no  
scroll yes no no¹ ? no no  
select yes no yes ? no yes  
submit yes yes yes yes no yes false
unload no no no ? no no  

¹Document scroll events will bubble to the window.

DOM Objects

{{ mediawiki.external('TODO') }}

See also

  1. {{ Note("w3c-dom") }} W3C Document Object Model (DOM) Level 3 Events Specification
  2. {{ Note("gecko-dom") }} Gecko DOM Reference
  3. {{ Note("mshtml-dom") }} {{ MSDN("ms533051", "HTML and DHTML Reference: Events") }}

{{ Block-title("Original Document Information") }}

Revision Source

<h3>Overview</h3>
<p>Events are things that happen to DOM elements in your page, such as mouse clicks or errors when an image fails to load.  When an event happens, the browser sends the event to the related element. If you've set a handler (a function) on that element, it gets called with related event info which means you "handled" the event.</p>
<p>More specifically, the event is sent to the element it happened in, plus all the elements that enclose it.  For instance, say you had a {{ HTMLElement("div") }} you wanted to act like a button:</p>
<pre>&lt;div onclick="getACupcake()"&gt;
  I &lt;strong&gt;Really&lt;/strong&gt; want a cupcake!
&lt;/div&gt;</pre>
<p>If someone clicks on the word <strong>Really</strong>, first the event is delivered to the {{ HTMLElement("strong") }}.  That has no handler, so it's delivered to the {{ HTMLElement("div") }}.  That handler can, if it wants, let outer elements try to handle the event, too, or it can cancel it.</p>
<p>In fact, the event traverses twice; first it travels from the window down to the target element (called <strong>capture</strong>) and then it travels back up to the window again (called <strong>bubbling</strong>).  And, there are two ways to set a handler: capture and bubble.  For instance, capture can allow a big element to intercept all clicks to its child elements, before they get it.  Unfortunately, Internet Explorer doesn't implement capture, so it's effectively unavailable for many web authors.  </p>
<h3>Handlers</h3>
<p>When a handler gets called, it gets an {{ domxref("Event") }} object as its first argument, which has lots of fields that describe about the event, such as which keystroke was hit, what the mouse coordinates were, the time at which the event happened, etc.  Only Internet Explorer versions lower than 9 uses the global <code>window.event</code> object instead of an argument.  There are many ways to set an event handler, each with its own quirks.  More info <a href="/DOM/element" title="DOM/element">here</a>.</p>
<h4>Inline</h4>
<pre style="margin-top: 0px; margin-right: 0px; margin-bottom: 1.7em; margin-left: 0px; padding-top: 10px; padding-right: 10px; padding-bottom: 10px; padding-left: 10px; border-top-width: 1px; border-right-width: 1px; border-bottom-width: 1px; border-left-width: 1px; border-top-style: solid; border-right-style: solid; border-bottom-style: solid; border-left-style: solid; border-top-color: rgb(223, 236, 241); border-right-color: rgb(223, 236, 241); border-bottom-color: rgb(223, 236, 241); border-left-color: rgb(223, 236, 241); overflow-x: auto; overflow-y: auto; font: normal normal normal 12px/normal 'Courier New', 'Andale Mono', monospace; color: rgb(37, 34, 29); ">&lt;div onclick='getACupcake(event)'&gt;
</pre>
<p>This first way is often the easiest; this just executes the specified JavaScript code. It makes a wrapper routine that gets your code snippet spliced into it.  A trailing semicolon is optional. You can stick huge amounts of code in there but watch your embedded quotes and backslash them if they're the same type.</p>
<p>With the {{ domxref("Event") }} object, IE works differently from other browsers.  In IE, the <strong>event</strong> global has the event object.  In Firefox and other browsers, the event is passed in as an argument to the wrapper named <strong>event</strong>.  If you do it like the above, you'll never know the difference.  Flash: I think IE7 and IE8 now also pass in the event handler.</p>
<p>This method of assigning events are highly discouraged since it goes against the seperation of content and the code, creates problems when multiple event handlers are to be used and may even create security holes in your web applications so beware.</p>
<h4>addEventListener()</h4>
<p>The classy way to set a handler is to use <code>addEventListener()</code> on the target.</p>
<pre>document.getElementById('cupcakeButton').addEventListener('click', getACupcake);
</pre>
<p>If you use this way, you can actually add multiple handlers for the same event on the same target.  You then can remove them if you need to with <code>removeEventListener()</code>.</p>
<p>Unfortunately, IE works differently from other browsers.  There is no <code>addEventListener()</code> function and there is an <code>attachEvent()</code> function instead. It is used like below:</p>
<pre>document.getElementById('cupcakeButton').attachEvent('onclick', getACupcake); 
</pre>
<div class="note"><strong>Note:</strong> Internet Explorer 9 adds support for &lt;code&gt;addEventListener()&lt;/code&gt;.</div>
<h4>Assigning to event handler properties</h4>
<p>The old way is to just assign it like this:</p>
<pre>document.getElementById('cupcakeButton').onclick = getACupcake;</pre>
<p>As above, the event object is either a global or an argument.  This method may have problems and is not the preferred method, but it still works and a lot of people still use it. Also Dean Edwards <a class=" external" href="http://dean.edwards.name/weblog/2005/10/add-event/" title="http://dean.edwards.name/weblog/2005/10/add-event/">presents</a> a cool usage of this method with cross-browser support for multiple event listeners.</p>
<h3>Event object</h3>
<p>The {{ domxref("Event") }} object your handler gets has more than a dozen properties.  Again, IE tends to be different on several areas.  In fact, when it comes to keystrokes, and wheel events, they're all different because the W3C didn't define the standard until years later.  </p>
<p><code>event.target</code> is the original element the event happened to.  However, Internet Explorer calls it <code>event.srcElement</code>.  In fact, Chrome and Safari started setting both.  You can do this for maximum compatibility:</p>
<pre>function getACupcake(event) {
  var target = event.target || event.srcElement;
  target.style.backgroundColor = '#F00';  // use it
}</pre>
<p> Check out the <a class=" external" href="http://quirksmode.org/" title="http://quirksmode.org/">Quirks Mode site</a> for more info about browser differences.</p>
<h3 name="Events">Events</h3>
<table class="standard-table" style="width: 100%;"> <tbody> <tr> <th rowspan="2">Event</th> <th colspan="2">W3C DOM Level 3{{ Ref("w3c-dom") }}</th> <th colspan="2">Gecko DOM (FF2){{ Ref("gecko-dom") }}</th> <th colspan="2">MSHTML DOM (IE){{ Ref("mshtml-dom") }}</th> <th rowspan="2">Cancel Value ({{ mediawiki.external('X') }}HTML)</th> </tr> <tr> <th>Bubbles</th> <th>Cancelable</th> <th>Bubbles</th> <th>Cancelable</th> <th>Bubbles</th> <th>Cancelable</th> </tr> <tr> <th colspan="8">User interface event types</th> </tr> <tr> <td>DOMActivate</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>?</td> <td>yes(?)</td> <td>no(?)</td> <td>?</td> </tr> <tr> <td>DOMFocusIn</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMFocusOut</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>blur</td> <td>no</td> <td>no</td> <td>no</td> <td>?</td> <td>no</td> <td>no</td> <td> </td> </tr> <tr> <td>focus</td> <td>no</td> <td>no</td> <td>no</td> <td>?</td> <td>no</td> <td>no</td> <td> </td> </tr> <tr> <th colspan="8">Text event types</th> </tr> <tr> <td>textInput</td> <td>yes</td> <td>yes</td> <td>?</td> <td>?</td> <td>-</td> <td>-</td> <td>?</td> </tr> <tr> <th colspan="8">Mouse event types</th> </tr> <tr> <td>click</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td><code>false</code></td> </tr> <tr> <td>mousedown</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>?</td> <td>yes</td> <td>yes</td> <td>?</td> </tr> <tr> <td>mousemove</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>?</td> <td>yes</td> <td>no</td> <td>?</td> </tr> <tr> <td>mouseover</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td><code>true</code></td> </tr> <tr> <td>mouseout</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>no</td> <td><code>true</code></td> </tr> <tr> <td>mouseup</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>?</td> <td>yes</td> <td>yes</td> <td>?</td> </tr> <tr> <th colspan="8">Keyboard event types</th> </tr> <tr> <td>keydown</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td><code>false</code></td> </tr> <tr> <td>keyup</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>no</td> <td><code>false</code></td> </tr> <tr> <td>keypress (<em>proprietary</em>, see <code>textInput</code>)</td> <td>-</td> <td>-</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td><code>false</code></td> </tr> <tr> <th colspan="8">Mutation and mutation name event types</th> </tr> <tr> <td>DOMSubtreeModified</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMNodeInserted</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMNodeRemoved</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMNodeRemovedFromDocument</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMNodeInsertedIntoDocument</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMAttrModified</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMCharacterDataModified</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMElementNameChanged</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <td>DOMAttributeNameChanged</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>-</td> <td>-</td> <td> </td> </tr> <tr> <th colspan="8">Basic event types</th> </tr> <tr> <td>abort</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>no</td> <td>yes</td> <td> </td> </tr> <tr> <td>beforeunload</td> <td>-</td> <td>-</td> <td>no</td> <td>?</td> <td>no</td> <td>yes</td> <td> Any string</td> </tr> <tr> <td>change</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>no</td> <td>yes</td> <td> </td> </tr> <tr> <td>error</td> <td>yes</td> <td>no</td> <td>no</td> <td>yes</td> <td>no</td> <td>yes</td> <td><code>true</code></td> </tr> <tr> <td>load</td> <td>no</td> <td>no</td> <td>no</td> <td>?</td> <td>no</td> <td>no</td> <td> </td> </tr> <tr> <td>reset</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>?</td> <td>no</td> <td>yes</td> <td>?</td> </tr> <tr> <td>resize</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>no</td> <td>no</td> <td> </td> </tr> <tr> <td>scroll</td> <td>yes</td> <td>no</td> <td>no¹</td> <td>?</td> <td>no</td> <td>no</td> <td> </td> </tr> <tr> <td>select</td> <td>yes</td> <td>no</td> <td>yes</td> <td>?</td> <td>no</td> <td>yes</td> <td> </td> </tr> <tr> <td>submit</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>yes</td> <td>no</td> <td>yes</td> <td><code>false</code></td> </tr> <tr> <td>unload</td> <td>no</td> <td>no</td> <td>no</td> <td>?</td> <td>no</td> <td>no</td> <td> </td> </tr> </tbody>
</table>
<p>¹Document scroll events will bubble to the window.</p>
<h3 name="DOM_Objects">DOM Objects</h3>
<p>{{ mediawiki.external('TODO') }}</p>
<h3 name="See_also">See also</h3>
<ol> <li>{{ Note("w3c-dom") }} <a class="external" href="http://www.w3.org/TR/DOM-Level-3-Events/">W3C Document Object Model (DOM) Level 3 Events Specification</a></li> <li>{{ Note("gecko-dom") }} <a href="/en/DOM" title="en/DOM">Gecko DOM Reference</a></li> <li>{{ Note("mshtml-dom") }} {{ MSDN("ms533051", "HTML and DHTML Reference: Events") }}</li>
</ol>
<div class="originaldocinfo">
<p>{{ Block-title("Original Document Information") }}</p>
<ul> <li>Author: Thomas 'PointedEars' Lahn &lt;<a class=" link-mailto" href="mailto:dom@PointedEars.de" rel="freelink">dom@PointedEars.de</a>&gt;</li> <li>Copyright Information: © 2007 by individual MDC contributors (see history); content available under a <a href="/Project:en/Copyrights" title="Project:en/Copyrights">Creative Commons license</a></li>
</ul>
</div>
Revert to this revision