web component

A minimal parent class for web components.

This extends the native HTMLElement, and adds some methods to help with events.

See a live demonstration

Contents

• install
• tl;dr
• Example
  • Create a component
  • Add the component to the DOM
  • Listen for events
  • Emit a namespaced event from the instance
  • Listen for a namespaced event
  • Emit a plain string (not namespaced) event
• Modules
  • ESM
  • Common JS
• methods
  • emit(name:string, opts:{ bubbles?, cancelable?, detail? }):boolean
  • dispatch (type, opts)
  • event (name:string):string
  • qs
  • qsa
  • element.qs & element.qsa
• Misc
  • /util
• Develop
• Test
• See also

install

npm i -S @substrate-system/web-component

tl;dr

• use .emit to emit a namepsaced event
• use .dispatch to emit a non-namespaced event
• use .event(name) to get the namespaced event type
• extend the factory function to create a web component

Example

Create a component

Use the factory function to create a new web component.

import { WebComponent } from '@substrate-system/web-component'

class AnotherElement extends WebComponent.create('another-element') {
    connectedCallback () {
        this.innerHTML = `<div>
            hello again
        </div>`
    }
}

// call custom customElements.define with the right tag name
AnotherElement.define()

The new component will have a property NAME on the class that is equal to the name you passed in. The component name should be kebab case.

Add the component to the DOM

document.body.innerHTML += '<another-element></another-element>'

Listen for events

Use a helper method, WebComponent.event(name:string), to get a namespaced event name.

// find the instance
const el = document.querySelector('my-element')

// listen for namespaced events
el?.addEventListener(MyElement.event('hello'), ev => {
    console.log(ev.detail)  // => 'some data'
})

// listen for non-namespaced events
el?.addEventListener('hello', ev => {
    console.log(ev.detail)  // => 'some data again'
})

Emit a namespaced event from the instance

// find the instance
const el = document.querySelector('my-element')

// dispatch an event
el?.emit('hello', { detail: 'some data' })  // => `my-element:hello`

Listen for a namespaced event

Use the static method .event to get a namespaced event name.

class ExampleComponent extends WebComponent {
    tag = 'example-component'
    // ...
}

const ev = ExampleComponent.event('click')
// => 'example-component:click'

Emit a plain string (not namespaced) event

Don't namespace the event name, just emit the literal string.

const el = document.querySelector('my-element')

// dispatch an event as plain string, not namespaced
el?.dispatch('hello', { detail: 'some data again' })  // => `hello`

Modules

ESM

This exposes ESM and common JS via package.json exports field.

const { WebComponent } = import '@substrate-system/web-component'

Common JS

const { WebCompponent } = require('@substrate-system/web-component')

methods

emit(name:string, opts:{ bubbles?, cancelable?, detail? }):boolean

This will emit a CustomEvent, namespaced according to a convention.

The return value is the same as the native .dispatchEvent method,

returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

Because the event is namespaced, we can use event bubbling while minimizing event name collisions.

The naming convention is to take the NAME property of the class, and append a string :event-name.

So emit('test') dispatches an event like my-element:test.

class MyElement {
    NAME = 'my-element'  // <-- for event namespace
    // ...
}

// ... then use the element in markup ...

const el = document.querySelector('my-element')

// 'my-element:test' event
el.addEventListener(MyElement.event('test'), ev => {
    console.log(ev.detail)  // => 'some data'
})

// ... in the future ...

el.emit('test', 'some data')  // dispatch `my-element:test` event

See also, Custom events in Web Components

---

dispatch (type, opts)

Create and emit an event, no namespacing. The return value is the same as the native .dispatchEvent method,

returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

That is, it returns true if it was not preventDetaulted.

dispatch (type:string, opts:Partial<{
    bubbles,
    cancelable,
    detail
}>):boolean

dispatch example

const el = document.querySelector('my-element')
el.dispatch('change')  // => 'change' event

---

event (name:string):string

Return the namespaced event name.

event example

MyElement.event('change')  // => 'my-element:change'

qs

A convenient shortcut to element.querySelector.

qs (selector:string):HTMLElement|null

qsa

Shortcut to document.querySelectorAll

qsa (selector:string):ReturnType<typeof document.querySelectorAll>

element.qs & element.qsa

A shortcut to element.querySelector & element.querySelectorAll.

example

const myElement = document.querySelector('my-element')
debug('the namespaced event...', MyElement.event('aaa'))

// query inside the element 
const buttons = myElement?.qsa('button')

---

Misc

/util

Various functions.

qs

A convenient shortcut to document.querySelector.

import { qs } from 'substrate-system/web-component/qs'

qsa

A shortcut to document.querySelectorAll.

import { qsa } from 'substrate-system/web-component/qsa'

isRegistered(name:string)

Check if an element name has been used already.

function isRegistered (elName:string):boolean

import { isRegistered } from '@substrate-system/web-component/util'

example

import { isRegistered } from '@substrate-system/web-component/util'

if (!isRegistered('example-component')) {
    customElements.define('example-component', ExampleComponent)
}

define(name:string, element:CustomElementConstructor)

Add a component to the custom element registry.

This uses isRegistered, so it will not throw if the name has been taken already.

import { define } from '@substrate-system/web-component/util'

function define (name:string, element:CustomElementConstructor) {

---

Develop

Start a localhost server:

npm start

---

Test

npm test

---

See also

• Custom events in Web Components
• Web Component lifecycle methods
• How to detect when attributes change on a Web Component
• Handling asychronous rendering in Web Components
• Accessible Icon Buttons
• Inclusively Hidden