JavaScript CustomEvent

By  on  

JavaScript events have been the gateway to user interaction within the browser since its inception. Not only do events tell us when an interaction happens, but events tell us type of interaction, the nodes involved, and provide us methods for working with the event. Creating custom events and triggering them have always been trickier. Using JavaScript's CustomEvent API, that trickery can be eliminated. The CustomEvent API allows developers to not only create custom events but trigger them on DOM nodes, passing data along the way. Best of all, the API is super simple!

The JavaScript

When working with customizing events, there's two components included in an event being "custom": a custom event name and the ability to trigger that event. Adding an event listener to an element, however, stays the same:

myElement.addEventListener("userLogin", function(e) {
	console.info("Event is: ", e);
	console.info("Custom data is: ", e.detail);
})

Here we've added a userLogin event, just as easily as we could add a native mouseover or focus event -- that's not special. The special part is creating and triggering the event:

// First create the event
var myEvent = new CustomEvent("userLogin", {
	detail: {
		username: "davidwalsh"
	}
});

// Trigger it!
myElement.dispatchEvent(myEvent);

The CustomEvent constructor allows for creation of the custom event, allowing you to pass both a custom event name as well as a number of special properties; dispatchEvent triggers the event on the given element. Let's make the event to be triggered super-customized by configuring its bubbling, cancelable, detail properties:

var myEvent = new CustomEvent("userLogin", {
	detail: {
		username: "davidwalsh"
	},
	bubbles: true,
	cancelable: false
});

Creating and trigger custom events with custom data is incredibly useful. Not only can you create your own naming convention for events, but you may also pass custom data along the way! You can keep up with browser support on the CustomEvent API on MDN, but this API is available in most modern browsers.

Recent Features

  • By
    Responsive Images: The Ultimate Guide

    Chances are that any Web designers using our Ghostlab browser testing app, which allows seamless testing across all devices simultaneously, will have worked with responsive design in some shape or form. And as today's websites and devices become ever more varied, a plethora of responsive images...

  • By
    Camera and Video Control with HTML5

    Client-side APIs on mobile and desktop devices are quickly providing the same APIs.  Of course our mobile devices got access to some of these APIs first, but those APIs are slowly making their way to the desktop.  One of those APIs is the getUserMedia API...

Incredible Demos

  • By
    Use Custom Missing Image Graphics Using Dojo

    A few months back I posted an article about how you can use your own "missing image" graphics when an image fails to load using MooTools and jQuery. Here's how to do the same using Dojo. The HTML We'll delegate the image to display by class...

  • By
    Generate Dojo GFX Drawings from SVG Files

    One of the most awesome parts of the Dojo / Dijit / DojoX family is the amazing GFX library.  GFX lives within the dojox.gfx namespace and provides the foundation of Dojo's charting, drawing, and sketch libraries.  GFX allows you to create vector graphics (SVG, VML...

Discussion

  1. This looks really good, it resembles by 99% the way Actionscript3 handles events and custom events, and I have to say it is really useful to be able to dispatch custom events with or without custom data.

    Thanks.

  2. Manu

    Good article David ! Some framework propose an implementation. Dojo use dojo/on to expose CustomEvent.

  3. Nice way to show the concept of Custom Event, it is deeply explanatory and helpful. Thanks David.

  4. Nice post, It looks very straight forward. Can you have sub events or events that trigger other events?

  5. Georgiy

    That’s great, but how to remove listeners for such events?
    Traditional way, i.e. el.removeEventListener('userLogin', callback) doesn’t work =(

  6. Georgiy

    UPDATE to previous comment: my fault, removeEventListener works, I just tried remove all of the callbacks, not a single one, but that’s another story.

  7. Humberto

    I’d been reading about CustomEvent interface, but when is it useful, seeing that I need to dispatch it manually?

  8. Ram

    Nice post…

    Looks like IE 10 onwards there is no support for CustomEvent constructor…

    https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent?redirectlocale=en-US&redirectslug=Web%2FAPI%2FEvent%2FCustomEvent

  9. Hank

    If you are allowed to use JQuery for your projects, one simple Trigger takes care of it all! Across all browsers too!

  10. Diego

    Sorry, but i don’t understand the concept, who is firing the event?. u attached the event to an specific node with the dispatchEvent but it does not trigger the event handler.
    How can I really trigger the code inside the handler?

    • @Diego you would call the myElement.dispatchEvent(myEvent); from within your own JavaScript code whereever you want your event to fire. FOr example if you are building a Slider/Slideshow then you could have a custom event that is triggered when you slide to a new slide

  11. Mani Kiran

    Thanks for the article.

    Quick question:
    if we want to dispatch the event multiple times with different data then how can we
    d that?

Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!