Custom Elements Overview & Registration

Technical Deep Dive & Specifications

The CustomElementRegistry Interface

Every browser window exposes a global registry instance at window.customElements. It implements the CustomElementRegistry interface:

+-----------------------------------------------------------------------------------------------+
|                                    window.customElements                                      |
|                                                                                               |
|   +-----------------------+   +-----------------------+   +-------------------------------+   |
|   | .define('app-card', C)|   | .get('app-card')      |   | .whenDefined('app-card')      |   |
|   | Registers class 'C'   |   | Returns class C       |   | Returns Promise for lazy load |   |
|   +-----------------------+   +-----------------------+   +-------------------------------+   |
+-----------------------------------------------------------------------------------------------+

Valid Custom Element Naming Rules (WHATWG Specification)

The HTML Living Standard enforces strict lexical constraints on custom element names:

1. Mandatory Hyphen (-): Must contain at least one hyphen (e.g., user-profile, fancy-button, my-super-long-tag-name). This ensures forward compatibility so the W3C/WHATWG can introduce new single-word HTML tags (like <dialog> or <search>) without breaking user code.
2. First Character Restriction: Must begin with an ASCII lowercase letter (a-z).
3. Prohibited Characters: Cannot contain uppercase ASCII characters (A-Z). Tag names in HTML are case-insensitive when parsed, but custom element definitions are strictly lowercase.
4. PCENChar (Potential Custom Element Name Character): Characters after the first letter may include a-z, 0-9, -, ., _, and specific Unicode character ranges.
5. Reserved / Forbidden Names: The following hyphenated names are strictly forbidden because they collide with legacy SVG or MathML specifications:
   • annotation-xml
   • color-profile
   • font-face
   • font-face-src
   • font-face-uri
   • font-face-format
   • font-face-name
   • missing-glyph

VALID:
  <user-avatar>        -> Starts with 'u', contains '-'
  <chart-2d>           -> Contains digits and '-'
  <super-cool-button>  -> Multiple hyphens allowed

INVALID:
  <useravatar>         -> Throws NotSupportedError (missing hyphen)
  <2-gauge>            -> Throws NotSupportedError (must start with a-z)
  <user-Card>          -> Throws NotSupportedError (uppercase letters forbidden)
  <font-face>          -> Throws NotSupportedError (reserved legacy name)

The Element constructor() Rules

When writing the ES class for a custom element, the constructor() must adhere to strict browser invariants:

class MyElement extends HTMLElement {
  constructor() {
    // 1. MUST call super() first to establish prototype chain and engine binding
    super();

    // 2. DO NOT inspect attributes (this.getAttribute) -> Attributes not yet parsed!
    // 3. DO NOT inspect or mutate children (this.appendChild) -> Children not yet attached!
    // 4. DO initialize private state, bind methods, and attach Shadow DOM
    this._count = 0;
  }
}

Flash of Unstyled Content (FOUC) & :not(:defined)

When a browser parses an HTML document containing <custom-card>, it renders the raw DOM node before your JavaScript file downloads and executes customElements.define().

To prevent unstyled layout shifts, use the :not(:defined) pseudo-class:

/* Hide or display a skeleton placeholder until the JS class is registered */
user-badge:not(:defined) {
  display: inline-block;
  min-width: 120px;
  min-height: 32px;
  background: #e2e8f0;
  border-radius: 9999px;
  opacity: 0.5;
  animation: pulse 1.5s infinite;
}

user-badge:defined {
  display: inline-flex;
  opacity: 1;
  transition: opacity 0.2s ease-in;
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 14–22: user-badge:not(:defined) targets the element while it exists in the DOM as an unresolved node, rendering a pulsing skeleton box to prevent layout jumping.
• Lines 24–33: user-badge:defined styles the element once customElements.define() executes and upgrades the node.
• Line 41: <user-badge> is parsed into the DOM immediately. Because the browser hasn't encountered the definition yet, it creates a base HTMLElement instance.
• Lines 47–59: Class UserBadge extends HTMLElement. constructor() invokes super().
• Lines 62–65: customElements.whenDefined('user-badge') returns a Promise that settles as soon as registration occurs.
• Lines 68–71: customElements.define('user-badge', UserBadge) officially binds the tag name to the class constructor.

Expected Browser Render Output

1. 0 to 2 Seconds: The page displays a pulsing gray pill-shaped placeholder (:not(:defined)). Status indicates "Waiting for registration...".
2. At 2 Seconds: The Promise resolves, status turns green ("Registered & Upgraded!"), and the skeleton immediately transforms into a styled badge showing a green online dot, "Alex Rivera", and an "Admin" tag.