custom-element-registry

ℹ️ You don't need this tool if your project has a modern build process (with tools like Vite, Webpack, Parcel) This package was made for a legacy use-case, where it was undesired to implement complex build process, but there was a need to create a modern web app experience.

A lightweight service for dynamically loading and registering custom web components. Perfect for lazy-loading components or building modular applications.

Features

Dynamic loading of custom element modules
Automatic registration with the browser's CustomElementRegistry
Optional prefix support for namespacing components
Auto-generated tag names from class names (CamelCase to kebab-case)
Promise-based API for reliable post-load code execution
Browser compatibility check for custom elements support
Input validation with descriptive error messages
Works with vanilla JS, Lit, or any web component library

Installation

npm install @zoltanradics/custom-element-registry

Usage

Component File Structure

Your component files should export the class as default and optionally export a tagName:

// components/my-button.js

// Optional: explicitly define the tag name
export const tagName = 'my-button';

// Required: export the class as default
export default class MyButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    this.shadowRoot.innerHTML = `<button>Click me</button>`;
  }
}

// Note: Do NOT call customElements.define() - the registry handles this

If tagName is not exported, the registry will automatically generate it from the class name (e.g., MyButton → my-button).

Basic Usage

import customElementRegistry from '@zoltanradics/custom-element-registry';

// Define the component file paths to load
const componentPaths = [
  '/components/my-button.js',
  '/components/my-card.js',
  '/components/my-modal.js'
];

// Load and register all components
customElementRegistry(componentPaths)
  .then(() => {
    console.log('All components loaded and ready to use!');
    // Your post-load code here
  })
  .catch(error => {
    console.error('Failed to load components:', error);
  });

With Options

// Use a prefix to namespace your components
await customElementRegistry(componentPaths, {
  prefix: 'app',    // Components will be registered as app-my-button, app-my-card, etc.
  verbose: true     // Log registration messages to console
});

With async/await

async function initializeApp() {
  try {
    await customElementRegistry([
      '/components/header.js',
      '/components/footer.js',
      '/components/sidebar.js'
    ], { prefix: 'app' }); // Always optional

    // Components are now ready - render your app
    document.getElementById('app').innerHTML = `
      <app-header></app-header>
      <app-sidebar></app-sidebar>
      <app-footer></app-footer>
    `;
  } catch (error) {
    console.error('Initialization failed:', error);
  }
}

initializeApp();

API