The Web platform provides several ways to be notified of DOM events. Two common approaches are addEventListener() and the specific onevent handlers. This page focuses on how the latter work.

Registering on-event handlers

The onevent handlers are properties on certain DOM elements to manage how that element reacts to events. Elements can be interactive (links, buttons, images, forms…) or non-interactive (the base <body> element). Events are actions like:

  • Being clicked
  • Detecting pressed keys
  • Getting focus

The on-event handler is usually named with the event it reacts to, like onclick, onkeypress, onfocus, etc.

You can specify an on<…> event handler for a particular event (such as click) for a given object in different ways:

  • Adding an HTML attribute named on<eventtype>:
    <button onclick="handleClick">,
  • Or by setting the corresponding property from JavaScript:
    document.querySelector("button").onclick = function(event) { … }.

Note that each object can have only one onevent handler for that event (though that handler could call other functions). This is why addEventListener() is often preferable to be notified of events, especially for multiple event handlers for the same event and/or element.

Note that onevent handlers are called automatically, not at the programmer's will (although you can do so, such as with mybutton.onclick(myevent)) since they serve more as placeholders to which a real handler function can be assigned.

Non-element objects

Event handlers can also be set with properties on non-element objects that generate events, like window, document, XMLHttpRequest, and others. For example, for the progress event on instances of XMLHttpRequest:

const xhr = new XMLHttpRequest();
xhr.onprogress = function() { … };

Details

The value of HTML on<...> attributes and corresponding JavaScript properties

A handler registered via an on<…> attribute will be available from its corresponding on<…> property, but not the other way around:

<p id="a" onclick="alert('old')">Open the Developer Tools Console to see the output.</p>

<script>
  var el = document.getElementById("a");
  console.log("Attribute reflected as a property: ", el.onclick);
  // Prints: function onclick(event) { alert('old') }
  el.onclick = function() { alert('new') };
  console.log("Changed property to: ", el.onclick);
  // Prints: function () { alert('new') }
  console.log("Attribute value is unchanged: ", el.getAttribute("onclick"));
  // Prints: alert('old')
</script>

For historical reasons, some attributes/properties on the <body> and <frameset> elements instead set event handlers on their parent Window object. (The HTML specification names these: onblur, onerror, onfocus, onload, and onscroll.)

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

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 onerror.
  • event, source, lineno, colno, and error for the onerror event handler. Note that the event parameter actually contains the error message as a string.

When the event handler is invoked, the this keyword inside the handler is set to the DOM element on which the handler is registered. For more details, see the this keyword documentation.

The return value from the handler determines if the event is canceled. The specific handling of the return value depends on the kind of event; for details, see "The event handler processing algorithm" in the HTML specification.

When the event handler is invoked

TBD (non-capturing listener)

Terminology

The term event handler may refer to:

  • Any function or object that is 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)"> or window.onload = function() { … }.

When discussing the various methods of listening to events:

  • Event listener refers to a function or object registered via EventTarget.addEventListener()
  • Event handler refers to a function registered via on… attributes or properties

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'event handlers' in that specification.
Living Standard
HTML5
The definition of 'event handlers' in that specification.
Recommendation

Browser compatibility

Detecting the presence of event handler properties

You can detect the presence of an event handler property with 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. In the past, event handlers (onload, etc.) weren't implemented as IDL attributes in Gecko, so you were able to do this for those. Now you can't. This improves compatibility.

Document Tags and Contributors

Last updated by: Tigt,