Writing Custom HTML Elements

Motivation

One of the key features of HTML5 is semantically meaningful element tags. For example, <nav>, <header>, <cite>, etc are meant to convey meaning as well as purpose in a web page.

However, when I peruse a most web pages, I am bombarded with <div> after <div> after <div> which makes their purpose very hard to read indeed. In fact, a <div> is the quintessential meaningless element.

In my second portfolio project for Code Institute, I implemented a version of Rock, Paper, Scissors, Lizard, Spock! and I wanted to use my own custom elements which would convey meaning. For example, the following code snippet defines a <game-play-panel> element with a <player-card>, and <computer-card> as children.

<game-play-panel class="flex-container game-play-panel-area">
            <player-card class="grid-container player-area">
                <h2 id="player-card-header" class="player-color player-area">You</h2>
                <img id="player-choice-card" src="assets/images/question-player.png" alt="A question mark" class="tile">
            </player-card>

            <score-board class="grid-container score-area">
                <h2>Score</h2>
                <p id="player-score" class="player-color">0</p>
                <p id="computer-score" class="computer-color">0</p>
                <p id="round">Round <span id="round-value">--</span></p>
            </score-board>

            <computer-card class="grid-container computer-area">
                <h2 id="computer-card-header" class="computer-color">Shelbot</h2>
                <img id="computer-choice-card" src="assets/images/question-computer.png" alt="A question mark." class="tile">
            </computer-card>
</game-play-panel>

In this article, I am going to show you how to make your own custom HTML element.

Overview

The follow steps are needed to make your own HTML5 element.

1. You must give your element a name. That name must have a dash in it and no special characters. For example <game-area> is ok. <gamearea> or <gameArea> is not allowed.
2. You must write a class for that element in a JavaScript file.
3. You must register that element so that it becomes part of the DOM.
4. You must load the JavaScript file in whatever page you want to use those elements.

This sounds like a lot of steps but it is not that bad. So lets dive in.

Writing your own element

You have a lot of freedom here. You can make your own element that behaves in its own way - you decide how it will behave in the DOM or you can base your element on a pre-existing HTML5 element and customize it to your needs. In my case, I wanted my element to behave like a <div> so I based my custom element on the pre-existing <div> element. Let us say I want to create an element called <score-board>. Here is what you do.

1. Create a JavaScript file. Call it whatever you like, but I will call it elements.js.
2. In this file, declare a class called ScoreBoard that will extend the HTMLDivElement.

   class ScoreBoard extends HTMLDivElement {

}

There are other classes you can choose to extend. For example, there is HTMLParagraphElement, or HTMLBodyElement. You can read about them all here at The HTML DOM API.

Since I want my element to behave like a <div>, I chose to extend HTMLDivElement Note too the class name is in PascalCase. This is good style. The element will be named <score-board> but its class name will be ScoreBoard.

3. Write a constructor and call the super() method of the parent class. This is good old fashioned OOP here. The super() will call the constructor of the parent class, which is HTMLDivElement. That will give this custom element all of the properties of a <div> element. If we wanted to, we could add our own custom code and behavior to the element in the constructor after the super() call. To keep it simple, we will not do that here.

class ScoreBoard extends HTMLDivElement {
    constructor(){
        super();
    }
}

3. Now you have to register the the element so that it becomes part of the DOM. You do this by calling customElements.define() and pass in the name of your custom element, the class that defines its behavior, and an object that tells it which HTML element it inherits from.

customElements.define("score-board", ScoreBoard, { extends: "div" });

In the end, your elements.js file should look like this:

class ScoreBoard extends HTMLDivElement {
    constructor(){
        super();
    }
}

customElements.define("score-board", ScoreBoard, { extends: "div" });

NOTE: You can define the classes and register multiple elements in the same file. Here is a link to my source code if you want to take a look: custom-components.ts

4. The last step is to load the file into the <head> tag of whatever html page you want to use your new element.

<head>

<script src="elements.js"></script>

</head>

That's it! You can now use your custom element.

There is A LOT more you can do. You can set styles, content, etc. We will look at that in a later article.