Summary
The Web platform provides several ways to get notified of DOM events: {{domxref("EventTarget.addEventListener", "addEventListener()")}} and on<...> event handlers. This page focuses on the details of how the latter work.
Registering on<...> event handlers
You can specify an on<...> event handler for a particular event (such as {{event("click")}}) for a given object:
- Using an HTML {{Glossary("attribute")}} named
on{eventtype}on an element, for example:
<button onclick="return handleClick(event);">, - Or by setting the corresponding {{Glossary("property/JavaScript", "property")}} from JavaScript, for example:
document.getElementById("mybutton").onclick = function(event) { ... }.
Each object can have only one on<...> handler for a given event, which is why {{domxref("EventTarget.addEventListener", "addEventListener()")}} is often the better way to get notified of events.
Non-element objects
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 example:
xhr.onprogress = function() { ... }
Details
The value of HTML on<...> attributes and corresponding JavaScript properties
A handler registered via an on<...> attribute will be available via the corresponding on<...> property, but not the other way around:
<div id="a" onclick="alert('old')">Open the Developer Tools Console to see the output.</div>
<script>
window.onload = function () {
var div = document.getElementById("a");
console.log("Attribute reflected as a property: ", div.onclick.toString());
// Prints: function onclick(event) { alert('old') }
div.onclick = function() { alert('new') };
console.log("Changed property to: ", div.onclick.toString());
// Prints: function () { alert('new') }
console.log("Attribute value is unchanged: ", div.getAttribute("onclick"));
// Prints: alert('old')
}
</script>
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 specified as an HTML attribute, the specified code is wrapped into a function with the following parameters:
event- for all event handlers, except {{domxref("GlobalEventHandlers.onerror", "onerror")}}.event,source,lineno,colno, anderrorfor the {{domxref("GlobalEventHandlers.onerror", "onerror")}} event handler
When the event handler is invoked
TBD (non-capturing listener)
Terminology
The term event handler may be used to 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 in HTML or properties in web APIs, such as<button onclick="alert(this)">orwindow.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.
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.