Custom Elements

Introduction

A method for enabling the developer to define and use new types of DOM elements in a document. Custom elements consist of: name, type, namespace, prototype and callbacks. The custom element's name must contain a hypen minus (-) and must not contain any uppercase ASCII letters.

Registering Custom Elements

To register a custom element use the registerElement method of the document interface. It returns the custom element constructor.

var zBar = document.registerElement('z-bar');

Extending Native Elements

In order to extends native HTML elements as button, input, div, etc. you need to provide an object with 'prototype' and 'extends' elements, as second parameter to the registerElement method.

var zDiv = document.registerElement('z-div', {
  prototype: Object.create(HTMLDivElement.prototype),
  extends: 'div'
});

Instantiating Custom Elements

• Using the custom tags:

<z-bar></z-bar>

• Using the new operator:

document.body.appendChild(new zBar());

• Using the createElement method:

var element = document.createElement('z-bar');
document.body.appendChild(element);

Instantiating Custom Elements whose extends native elements

• Using the is attribute:

<div is="z-div"></div>

Using the new operator:

document.body.appendChild(new zDiv());

• Using the createElement method:

var element = document.createElement('div', 'z-div');
document.body.appendChild(element);

Lifecycle callbacks

Four callbacks are available:

createdCallback

Invoked when custom element instance is created.

attachedCallback

Invoked when custom element is appended to the document.

detachedCallback

Invoked when custom element is removed from the document.

attributeChangedCallback

Invoked when custom element's attribute is added, removed or changed.

Let's see how to define a callback on custom element:

var zProto = Object.create(HTMLElement.prototype);
zProto.createdCallback = function () {
    console.log('created');
};
zProto.attributeChangedCallback = function () {
    console.log('attribute changed');
};
var zBar = document.registerElement('z-bar', {
    prototype: zProto
});

Adding events, properties and methods

You can add extra functionality to your custom elements by adding events, methods and properties to their prototype, as much alike adding a callback, just before registering the custom element.

var zProto = Object.create(HTMLElement.prototype);
zProto.boo = 'woo';
zProto.getTest = function () {
    return 'test';
};
zProto.addEventListener('click', function () {
    console.log(this.boo);
});
var zBar = document.registerElement('z-bar', {
    prototype: zProto
});

Browser support

Custom elements are currently supported by Chrome 33+ and Opera 20+.

Polyfills

Since custom elements are not vastly supported yet, you should consider using polifills as Google's Polymer, Mozilla's X-Tag or Web Components.

This article describes what the custom elements are, how to create and use them. The code examples creates plain and simple elements, but the custom elements are much powerful, you can combine them with other Web Components like HTML templates and Shadow DOM. In fact they can encapsulate pretty much everything you can imagine, for example: calendar, time picker, google map, or even React component. To see custom elements in action check-out our examples.

More Web Components

• HTML Imports
• HTML Templates
• Shadow DOM

• Custom Elements (W3C Recommendation)
• Custom Elements (by Eric Bidelman, HTML5Rocks)

If you have questions about custom elements or web components itself, leave a comment below. Thanks so much for reading!