0.0.21 • Public • Published

Published on webcomponents.org


<xtal-in> is a vanilla-ish custom element that generates events with semantically meaningful event names.

The -in- in xtal-in- refers to an "input channel" -- which can be a clickable dom element, for example, or more abstract things like attributes changing.

In the groundbreaking blog post "Custom Elements That Work Anywhere", Rob Dodson blegs:

In general, don't bubble events unless they are semantically meaningful. For example, changed is not a very semantically meaningful event, whereas document-opened would be. Non-semantic events can leak up and another element may accidentally handle them.

Adding an event listener to an element, whose sole purpose is to bubble the event up with a different name, is a rather insulting task for the powerful and sophisticated JavaScript language to handle. JavaScript should only be bothered with important stuff, like reinventing the browser in an immutable abstraction layer that can time travel recursively.

<xtal-in click></xtal-in>
<button data-dispatch-onclick="wtf bubbles composed noblock">How did I get here?</button>
document.body.addEventListener('wtf', e =>{
    alert('Same as it ever was');

By default, xtal-in blocks the original event from propagating is optional, and prevents the event from propagating. Adding "noblock" allows the original event to propagate normally. Note that we specify whether this new semantically meaningful event should bubble and/or escape the shadow DOM cocoon ("composed")

You can also specify a test on the element spawning the event, using the if-matches attribute, which uses matches() under the hood:

<xtal-in click input></xtal-in>
<div data-dispatch-onclick="
    click: if(#talkingButton) type:¯\_(ツ)_/¯ bubbles composed
    input: if(#large_automobile) type:behind-the-wheel
<button id="talkingButton">My God! What have I done?</button>
<input type="text" id="large_automobile">

Monitoring Attribute Changes

In addition to listening for click or input events, one can listen for attribute change events:

<david-byrne beautiful-wife="Adelle Lutz" data-dispatch-on-attr-change="beautiful-wife: type:once-in-a-lifetime"></david-byrne>

Install the Polymer-CLI

First, make sure you have the Polymer CLI installed. Then run polymer serve to serve your element locally.

Viewing Your Element

$ polymer serve

Running Tests





Package Sidebar


npm i xtal-in

Weekly Downloads






Unpacked Size

108 kB

Total Files


Last publish


  • bahrus