Event constructor

Build-in event classes form a hierarchy, similar to DOM element classes. The root is the built-in Event class.
We can create Event objects like this:

  1. let event = new Event(type[, options]);

Arguments:

  • type – event type, a string like "click" or our own like "my-event".
  • options– the object with two optional properties:
    • bubbles: true/false – if true, then the event bubbles.
    • cancelable: true/false – if true, then the “default action” may be prevented. Later we’ll see what it means for custom events.
  • By default both are false: {bubbles: false, cancelable: false}.

dispatchEvent

After an event object is created, we should “run” it on an element using the call elem.dispatchEvent(event).
Then handlers react on it as if it were a regular browser event. If the event was created with the bubbles flag, then it bubbles.
In the example below the click event is initiated in JavaScript. The handler works same way as if the button was clicked:

  1. <button id="elem" onclick="alert('Click!');">Autoclick</button>
  2. <script>
  3.   let event = new Event("click");
  4.   elem.dispatchEvent(event);
  5. </script>

event.isTrusted
There is a way to tell a “real” user event from a script-generated one.
The property event.isTrusted is true for events that come from real user actions and false for script-generated events.

Custom events

For our own, completely new events types like "hello" we should use new CustomEvent. Technically CustomEvent is the same as Event, with one exception.
In the second argument (object) we can add an additional property detail for any custom information that we want to pass with the event.
For instance:

  1. <h1 id="elem">Hello for John!</h1>
  2. <script>
  3.   // additional details come with the event to the handler
  4.   elem.addEventListener("hello", function(event) {
  5.     alert(event.detail.name);
  6.   });
  7.   elem.dispatchEvent(new CustomEvent("hello", {
  8.     detail: { name: "John" }
  9.   }));
  10. </script>

The detail property can have any data. Technically we could live without, because we can assign any properties into a regular new Event object after its creation. But CustomEvent provides the special detail field for it to evade conflicts with other event properties.
Besides, the event class describes “what kind of event” it is, and if the event is custom, then we should use CustomEvent just to be clear about what it is.

event.preventDefault()

Many browser events have a “default action”, such as nagivating to a link, starting a selection, and so on.
For new, custom events, there are definitely no default browser actions, but a code that dispatches such event may have its own plans what to do after triggering the event.
By calling event.preventDefault(), an event handler may send a signal that those actions should be canceled.
In that case the call to elem.dispatchEvent(event) returns false. And the code that dispatched it knows that it shouldn’t continue.
Let’s see a practical example – a hiding rabbit (could be a closing menu or something else).
Below you can see a #rabbit and hide() function that dispatches "hide" event on it, to let all interested parties know that the rabbit is going to hide.
Any handler can listen for that event with rabbit.addEventListener('hide',...) and, if needed, cancel the action using event.preventDefault(). Then the rabbit won’t disappear:

  1. <pre id="rabbit">
  2.   |\   /|
  3.    \|_|/
  4.    /. .\
  5.   =\_Y_/=
  6.    {>o<}
  7. </pre>
  8. <button onclick="hide()">Hide()</button>
  9. <script>
  10.   // hide() will be called automatically in 2 seconds
  11.   function hide() {
  12.     let event = new CustomEvent("hide", {
  13.       cancelable: true // without that flag preventDefault doesn't work
  14.     });
  15.     if (!rabbit.dispatchEvent(event)) {
  16.       alert('The action was prevented by a handler');
  17.     } else {
  18.       rabbit.hidden = true;
  19.     }
  20.   }
  21.   rabbit.addEventListener('hide', function(event) {
  22.     if (confirm("Call preventDefault?")) {
  23.       event.preventDefault();
  24.     }
  25.   });
  26. </script>

Please note: the event must have the flag cancelable: true, otherwise the call event.preventDefault() is ignored.

Events-in-events are synchronous

Usually events are processed asynchronously. That is: if the browser is processing onclick and in the process a new event occurs, then it waits until the onclick processing is finished.
The exception is when one event is initiated from within another one.
Then the control jumps to the nested event handler, and after it goes back.
For instance, here the nested menu-open event is processed synchronously, during the onclick: