Custom Events

There are times when you want to inform the user of your web component that something has happened inside. This type of thing is done through events, click for example, but what if the event is not standard. The web component can create its own custom events and allow the user to keep an eye out for it.

<style>
  :host {
    display: inline-block;
  }
</style>
<div id="count">0</div>
<button id="plus">Add</button>
<button id="minus">Minus</button>
<button id="clear">Clear</button>

This is the inner HTML of the web component. We want to allow the user to increase and decrease a number. It is all very basic so far, but we also want to fire events whenever the number is changed to an odd or even number.

_plusClickEvent(event) {
  // Update count
  this._count++;
  this._countElement.innerText = this._count.toString();

  // If odd
  if (this._count % 2) {
    // Create odd event
    const oddEvent = new CustomEvent('odd', { detail: this._count });

    // Dispatch the event
    this.dispatchEvent(oddEvent);
  } else {
    // Create even event
    let evenEvent = new CustomEvent('even', { detail: this._count });

    // Dispatch the event
    this.dispatchEvent(evenEvent);
  }
}  

This is the plus button's click event. It first increases the count and then updates the count element with the new value. Then we check to see if the number is odd or even. To fire an event we need to create a CustomEvent object with the name of the event and any extra information relating to it. After this we need to dispatch the event, so that it can be processed by whoever is monitoring it.

<custom-event-example id="test"></custom-event-example>

To test this we have our web component. To monitor the custom event we need to use the addEventListener function.

// Get test element
const testElement = document.getElementById('test');

// Add events
testElement.addEventListener('odd', function (event) {
  customLogEvent('ODD: ' + event.detail.toString());
});

testElement.addEventListener('even', function (event) {
  customLogEvent('EVEN: ' + event.detail.toString());
});  

Here we are adding event listeners for the odd and even events, and we are just log them being fired. Take a look at the example below.

Composed Events

A custom event is very useful but by default it will not move through the shadow DOM. They will not bubble up through the DOM either. The standard click event, for example, will travel from a button all the way up the DOM, through any shadow DOMs, up to the root of the page.

To make a custom event behave more like a click event, you need to add some extra options to the CustomEvent constructor.

// Create test event (this can bubble through the shadow DOM)
const testEvent = new CustomEvent('test', { bubbles: true, composed: true });

Here we have added an object with two properties. bubbles is used to make the event travel up the DOM. composed is used to allow the event to travel through a shadow DOM. Without this last one, the event would stop at the first shadow DOM it came to.

In this example, the “Click Test” option fires the standard click event. This will move up, from the button, through the child and parent shadow DOMs, to the outside.

The “Internal Test” option will fire a test custom event with default settings. This is fired from the child web component, not from inside it, so it does reach the parent. But it does not pass through the parent shadow DOM to the outside.

The “External Test” option fires the test custom event but has the bubbles and composed settings set to true. This then allows the event to move up the DOM, through the parent shadow DOM and on to the outside.