Define Custom Elements

What Does Define Elements Mean?

Defining elements means registering a custom HTML tag with the browser using the customElements.define() method.

After an element is defined, the browser knows how to create, upgrade, and run the JavaScript class connected to that custom element.

Basic Define Element Example

class AppMessage extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <p>Hello from a defined custom element!</p>
    `;
  }
}

customElements.define("app-message", AppMessage);

<app-message></app-message>

The element name app-message is connected to the AppMessage class using customElements.define().

customElements.define() Syntax

customElements.define(name, constructor, options);

How Defining Elements Works

Custom Element Naming Rules

A hyphen is required so browsers can distinguish custom elements from built-in HTML elements.

Element Upgrade Example

<user-greeting name="John"></user-greeting>

<script>
  class UserGreeting extends HTMLElement {
    connectedCallback() {
      const name = this.getAttribute("name") || "Guest";

      this.innerHTML = `
        <p>Hello, ${name}!</p>
      `;
    }
  }

  customElements.define("user-greeting", UserGreeting);
</script>

The browser may see <user-greeting> before the class is registered. Once customElements.define() runs, the element is upgraded and its lifecycle callbacks run.

Checking If an Element Is Defined

const ExistingElement = customElements.get("app-message");

if (ExistingElement) {
  console.log("app-message is already defined");
}

Use customElements.get() to check whether a custom element has already been registered.

Avoid Duplicate Definitions

if (!customElements.get("app-message")) {
  customElements.define("app-message", AppMessage);
}

Defining the same element name more than once causes an error. Checking first prevents duplicate registration problems.

Waiting Until an Element Is Defined

customElements.whenDefined("user-card").then(() => {
  console.log("user-card is ready to use");
});

The customElements.whenDefined() method returns a Promise that resolves after the element has been registered.

Defining an Element With Shadow DOM

class InfoCard extends HTMLElement {
  constructor() {
    super();

    this.attachShadow({ mode: "open" });

    this.shadowRoot.innerHTML = `
      <style>
        .card {
          border: 1px solid #dee2e6;
          border-radius: 1rem;
          padding: 1rem;
          background: #ffffff;
        }

        h2 {
          color: #0d6efd;
          margin-top: 0;
        }
      </style>

      <article class="card">
        <h2><slot name="title">Info</slot></h2>
        <div><slot></slot></div>
      </article>
    `;
  }
}

customElements.define("info-card", InfoCard);

<info-card>
  <span slot="title">Profile</span>
  <p>This card uses Shadow DOM.</p>
</info-card>

After the element is defined, the browser connects the <info-card> tag to the InfoCard class and renders the Shadow DOM content.

Defining Customized Built-In Elements

class PrimaryButton extends HTMLButtonElement {
  connectedCallback() {
    this.classList.add("btn", "btn-primary");
  }
}

customElements.define("primary-button", PrimaryButton, {
  extends: "button"
});

<button is="primary-button">
  Save
</button>

Customized built-in elements extend native elements, but autonomous custom elements like <app-button> are more commonly used in Web Components.

Autonomous vs Customized Built-In Elements

When to Define Custom Elements

• You want to create a reusable custom HTML tag.
• You need a component that works without a specific framework.
• You want to package behavior, markup, and styles together.
• You are building a design system or component library.
• You want a browser-native component API.
• You need components that can be used across multiple applications.

Common Define Element Use Cases

• Define UI components like app-button, user-card, and site-header.
• Register design system components for reuse.
• Create framework-independent widgets.
• Upgrade server-rendered custom element tags after JavaScript loads.
• Build micro frontend UI blocks shared across teams.
• Expose reusable browser-native components in a package.

Define Elements Best Practices

• Use clear, lowercase, hyphenated custom element names.
• Check with customElements.get() before defining shared components.
• Use customElements.whenDefined() when code depends on a registered component.
• Prefer autonomous custom elements for broad browser compatibility and simpler usage.
• Keep element class names readable and aligned with tag names.
• Define elements once at module load time.
• Document the element name, attributes, properties, events, slots, and parts.

Common Define Element Mistakes

• Defining a custom element name without a hyphen.
• Calling customElements.define() more than once for the same name.
• Using native element names like button or header.
• Forgetting to import the JavaScript module that defines the element.
• Expecting the custom element to work before it is registered.
• Using unclear names that conflict across teams or packages.
• Not documenting the custom element public API.

Key Takeaways

• Use customElements.define() to register a custom element.
• Custom element names must include a hyphen.
• The browser stores definitions in the Custom Element Registry.
• Existing matching tags are upgraded after definition.
• Use customElements.get() to avoid duplicate definitions.
• Use customElements.whenDefined() to wait for registration.