Custom Elements

Posted on: August 8, 2015 by Dimitar Ivanov


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:
  • Using the new operator:
document.body.appendChild(new zBar());
  • Using the createElement method:
var element = document.createElement('z-bar');

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');

Lifecycle callbacks

Four callbacks are available:

Invoked when custom element instance is created.
Invoked when custom element is appended to the document.
Invoked when custom element is removed from the document.
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 () {
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); = 'woo';
zProto.getTest = function () {
    return 'test';
zProto.addEventListener('click', function () {
var zBar = document.registerElement('z-bar', {
    prototype: zProto

Browser support

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


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

Share this post

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


Comments are closed