mozilla

Revision 411219 of DOM event handlers

  • Revision slug: Web/Guide/DOM/Events/Event_handlers
  • Revision title: DOM event handlers
  • Revision id: 411219
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment describe what event handlers are, link to the spec, start documenting event handler details

Revision Content

Summary

A possible way to get notified of {{domxref("Event")}}s of a particular type (such as {{event("click")}}) for a given object is to specify the event handler using:

  • An HTML attribute named on{eventtype} on an element, for example: <button onclick="return handleClick(event);">,
  • or by setting the corresponding property from JavaScript, for example: document.getElementById("mybutton").onclick = function(event) { ... }.

If you're working with a modern browser, use {{domxref("EventTarget.addEventListener", "addEventListener()")}} instead.

The available events are documented in the events reference.

Details

Definitions

The term event handler may refer to:

  • any function or object registered to be notified of events,
  • or, more specifically, to the mechanism of registering event listeners via on... attributes or properties in HTML and other web APIs, such as <button onclick="alert(this)"> or window.onload = function() { /* ... */ }.

When discussing the various methods of listening to events,

  • event listener refers to a function or object registered via {{domxref("EventTarget.addEventListener()")}},
  • whereas event handler refers to a function registered via on... attributes or properties.

This page is about the specifics of registering event handlers using on... attributes and properties.

Objects that support event handlers

Event handlers on HTML elements can be set using attributes starting with "on" in the HTML markup (<button onclick="...">) or using {{domxref("Element.setAttribute")}}, and also via the {{ domxref("Element") }}'s properties named "on..." using JavaScript (i.e. element.onclick = function() { ... }).

Event handlers can also be set using properties on many non-element objects that generate events, including {{ domxref("window") }}, {{ domxref("document") }}, {{ domxref("XMLHttpRequest") }}, and others.

For historical reasons, some attributes/properties on the {{HTMLElement("body")}} and {{HTMLElement("frameset")}} elements actually set event handlers on their parent {{domxref("Window")}} object. (The HTML specification names these: onblur, onerror, onfocus, onload, onscroll.)

Event handler's parameters, this binding, and the return value

TBD

When the event handler is invoked

TBD (non-capturing listener)

Specifications

Specification Status Comment
{{SpecName('HTML WHATWG', 'webappapis.html#event-handler-attributes', 'event handlers')}} {{Spec2('HTML WHATWG')}}  
{{SpecName('HTML5 W3C', 'webappapis.html#event-handler-attributes', 'event handlers')}} {{Spec2('HTML5 W3C')}}  

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }}
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }} {{ CompatVersionUnknown() }}

Event handler changes in Firefox 9

In order to better match the specifications, and improve cross-browser compatibility, the way event handlers were implemented at a fundamental level changed in Gecko 9.0 {{ geckoRelease("9.0") }}.

Specifically, in the past, event handlers were not correctly implemented as standard IDL attributes. In Gecko 9.0, this was changed. Because of this, certain behaviors of event handlers in Gecko have changed. In particular, they now behave in all the ways standard IDL attributes behave. In most cases, this shouldn't affect web or add-on content at all; however, there are a few specific things to watch out for.

Detecting the presence of event handler properties

You can now detect the presence of an event handler property (that is, for example, onload), using the JavaScript in operator. For example:

if ("onsomenewfeature" in window) {
  /* do something amazing */
}

Event handlers and prototypes

You can't set or access the values of any IDL-defined attributes on DOM prototype objects; that means you can't, for example, change Window.prototype.onload anymore. In the past, event handlers (onload, etc) weren't really implemented as IDL attributes in Gecko, so you were able to do this for those. Now you can't. This improves compatibility.

Revision Source

<h2>Summary</h2>
<p>A possible way to get notified of {{domxref("Event")}}s of a particular type (such as {{event("click")}}) for a given object is to specify the <strong>event handler</strong> using:</p>
<ul>
  <li>An HTML attribute named <code>on{eventtype}</code> on an element, for example: <code>&lt;button onclick="return handleClick(event);"&gt;</code>,</li>
  <li>or by setting the corresponding property from JavaScript, for example: <code>document.getElementById("mybutton").onclick = function(event) { ... }</code>.</li>
</ul>
<p>If you're working with a modern browser, use {{domxref("EventTarget.addEventListener", "addEventListener()")}} instead.</p>
<p>The available events are documented in the <a href="/en-US/docs/Web/Reference/Events">events reference</a>.</p>
<h2>Details</h2>
<h3>Definitions</h3>
<p>The term <strong>event handler</strong> may refer to:</p>
<ul>
  <li>any function or object registered to be notified of events,</li>
  <li>or, more specifically, to the mechanism of registering event listeners via <code>on...</code> attributes or properties in HTML and other web APIs, such as <code>&lt;button onclick="alert(this)"&gt;</code> or <code>window.onload = function() { /* ... */ }</code>.</li>
</ul>
<p>When discussing the various methods of listening to events,</p>
<ul>
  <li><strong>event listener</strong> refers to a function or object registered via {{domxref("EventTarget.addEventListener()")}},</li>
  <li>whereas <strong>event handler</strong> refers to a function registered via <code>on...</code> attributes or properties.</li>
</ul>
<p>This page is about the specifics of registering event handlers using <code>on...</code> attributes and properties.</p>
<h3>Objects that support event handlers</h3>
<p>Event handlers on <strong><a href="/en-US/docs/Web/HTML/Element" title="/en-US/docs/Web/HTML/Element">HTML elements</a></strong> can be set using <strong>attributes</strong> starting with "on" in the HTML markup (<code>&lt;button onclick="..."&gt;</code>) or using {{domxref("Element.setAttribute")}}, and also via the {{ domxref("Element") }}'s <strong>properties</strong> named "on..." using JavaScript (i.e. <code><em>element</em>.onclick = function() { ... }</code>).</p>
<p>Event handlers can also be set using <strong>properties</strong> on many <strong>non-element objects</strong> that generate events, including {{ domxref("window") }}, {{ domxref("document") }}, {{ domxref("XMLHttpRequest") }}, and others.</p>
<p>For historical reasons, some attributes/properties on the {{HTMLElement("body")}} and {{HTMLElement("frameset")}} elements actually set event handlers on their parent {{domxref("Window")}} object. (The HTML specification names these: <code>onblur</code>, <code>onerror</code>, <code>onfocus</code>, <code>onload</code>, <code>onscroll</code>.)</p>
<h3>Event handler's parameters, <code>this</code> binding, and the return value</h3>
<p>TBD</p>
<h3>When the event handler is invoked</h3>
<p>TBD (non-capturing listener)</p>
<h2 id="Specifications" name="Specifications">Specifications</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{SpecName('HTML WHATWG', 'webappapis.html#event-handler-attributes', 'event handlers')}}</td>
      <td>{{Spec2('HTML WHATWG')}}</td>
      <td>&nbsp;</td>
    </tr>
    <tr>
      <td>{{SpecName('HTML5 W3C', 'webappapis.html#event-handler-attributes', 'event handlers')}}</td>
      <td>{{Spec2('HTML5 W3C')}}</td>
      <td>&nbsp;</td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h3>Event handler changes in Firefox 9</h3>
<p>In order to better match the specifications, and improve cross-browser compatibility, the way event handlers were implemented at a fundamental level changed in Gecko 9.0 {{ geckoRelease("9.0") }}.</p>
<p>Specifically, in the past, event handlers were not correctly implemented as standard IDL attributes. In Gecko 9.0, this was changed. Because of this, certain behaviors of event handlers in Gecko have changed. In particular, they now behave in all the ways standard IDL attributes behave. In most cases, this shouldn't affect web or add-on content at all; however, there are a few specific things to watch out for.</p>
<h4 id="Detecting_the_presence_of_event_handler_properties">Detecting the presence of event handler properties</h4>
<p>You can now detect the presence of an event handler property (that is, for example, <code>onload</code>), using the JavaScript <a href="/en/JavaScript/Reference/Operators/in" title="en/JavaScript/Reference/Operators/in"><code>in</code></a> operator. For example:</p>
<pre class="brush: js">
if ("onsomenewfeature" in window) {
&nbsp; /* do something amazing */
}
</pre>
<h4 id="Event_handlers_and_prototypes">Event handlers and prototypes</h4>
<p>You can't set or access the values of any IDL-defined attributes on DOM prototype objects; that means you can't, for example, change <code>Window.prototype.onload</code> anymore. In the past, event handlers (<code>onload</code>, etc) weren't really implemented as IDL attributes in Gecko, so you were able to do this for those. Now you can't. This improves compatibility.</p>
Revert to this revision