ElementBuilder

The class ElementBuilder provides services to enhance and register a custom element. It's the main builder, the entry point of the library.

The static method CustomElement.get(constructor) returns a fresh builder. The method expects the constructor of the custom element.

import {ElementBuilder} from '@tmorin/ceb'
// defines the custom element class
class MyCustomElement extends HTMLElement {
    constructor() {
        super()
    }
}
// creates the builder
const builder = ElementBuilder.get(MyCustomElement)

The builder and underlying decorators are also technically documented: ElementBuilder.

Registering a new custom element

A custom element is registered with the method ElementBuilder#register().

import {ElementBuilder} from '@tmorin/ceb'
// defines the custom element class
class MyCustomElement extends HTMLElement {
    constructor() {
        super();
    }
}
// creates the builder
const builder = ElementBuilder.get(MyCustomElement)
// register the custom element
builder.register()

The custom element can also be registered by a decorator.

import {ElementBuilder} from '@tmorin/ceb'
// register the custom element
@ElementBuilder.element<MyCustomElement>()
// defines the custom element class
class MyCustomElement extends HTMLElement {
    constructor() {
        super()
    }
}

By default, the name of the custom element is the kebab case of the class name. So, MyCustomElement becomes my-custom-element.

Once registered, the custom element can be created as any other HTML elements.

<!-- creates the custom element in HTML as any other HTML elements -->
<my-custom-element></my-custom-element>
// creates the custom element from its tag name
const myCustomElement = document.createElement('my-custom-element')
// appends the custom element as any other regular HTML element
document.body.append(myCustomElement)

Extending a built-in element

To register custom element which extends a built-in HTML elements, the tag name of the extended element has to be provided using the method ElementBuilder#extends().

import {ElementBuilder} from '@tmorin/ceb'
// defines the custom element class
class MyCustomButton extends HTMLButtonElement {
    constructor() {
        super()
    }
}
// creates the builder
const builder = ElementBuilder.get(MyCustomButton)
// provides the tag name of HTMLButtonElement
builder.extends('button')
// register the custom element
builder.register()

The extended HTML element can also be provided with the decorator.

import {ElementBuilder} from '@tmorin/ceb'
// register the custom element
@ElementBuilder.element<MyCustomButton>({
    // provides the tag name of HTMLButtonElement
    extends: 'button'
})
// defines the custom element class
class MyCustomButton extends HTMLButtonElement {
    constructor() {
        super()
    }
}

Once registered, the custom element can be created.

<!-- creates the extended HTML element using the `is` attribute -->
<button is="my-custom-button"></button>
// creates the extended HTML element
const myCustomElement = document.createElement('button', {is: 'my-custom-button'})
// appends the extended HTML element as any other regular HTML element
document.body.append(myCustomElement)

Overriding the name of the custom element

The name of the custom element can be overridden using the method ElementBuilder#name(tagName).

import {ElementBuilder} from '@tmorin/ceb'
// defines the custom element class
class MyCustomElementBis extends HTMLElement {
    constructor() {
        super()
    }
}
// creates the builder
const builder = ElementBuilder.get(MyCustomElementBis)
// overrides the default tag name
builder.name('another-name')
// register the custom element
builder.register()

The name of the custom element can also be provided with the decorator.

import {ElementBuilder} from '@tmorin/ceb'
// register the custom element
@ElementBuilder.element<MyCustomElementBis>({
    // overrides the default tag name
    name: 'another-name'
})
// defines the custom element class
class MyCustomElementBis extends HTMLButtonElement {
    constructor() {
        super()
    }
}

In this case, the name of the custom element is another-name.

<!-- creates the custom element in HTML as any other HTML elements -->
<another-name></another-name>

An example

The registered custom element is a simple element having the text content Hello! I'm <the element's name>..

See the Pen ceb - ElementBuilder by Thibault Morin (@tmorin) on CodePen.