Custom Elements: Create Your Own HTML Tags

Why it exists

Standard HTML has a limited set of tags. For complex UIs, developers often end up with nested divs that lack semantic meaning, like .... Custom Elements were created to solve this, allowing developers to define new, meaningful, and self-contained HTML elements.

The mental model

Think of Custom Elements as creating your own vocabulary for HTML. Instead of assembling generic div and span blocks into a "card," you can define a <product-card> element. The browser then knows exactly what a <product-card> is, including its structure, styles, and interactive behavior, because you've provided the blueprint in JavaScript.

How it works

The process has two main steps. First, you define the element's behavior in a JavaScript class that extends HTMLElement. Inside this class, you can implement lifecycle callbacks—special methods the browser calls automatically when the element is added to the page, removed, or has an attribute change. Second, you register your new element with the browser by calling customElements.define('element-name', YourClass). The name must contain a hyphen to avoid conflicts with standard HTML tags. Once registered, you can use <element-name> directly in your HTML.

When to use it

Use Custom Elements when you need to create reusable UI components that are framework-agnostic. They are perfect for building design systems, widget libraries, or any feature that needs to be encapsulated and easily shared. Because they are a web standard, they work in any major browser and with any (or no) JavaScript framework.

When not to use it

There are two types: autonomous elements (like <my-element>) and customized built-in elements (like ). Customized built-ins, which extend existing HTML tags, are not supported in Safari. For this reason, you should avoid them if you need broad browser compatibility. Stick to autonomous elements for cross-browser projects.

One canonical example

A minimal autonomous element for a pop-up. First, define the class: class PopupInfo extends HTMLElement { constructor() { super(); } }. Then, register it with the browser: customElements.define('popup-info', PopupInfo);. Now, you can use it directly in your HTML: <popup-info></popup-info>. The browser sees this tag, finds its registered class, and creates an instance to manage its behavior.