or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bundle-usage.mddynamic-loading.mdes5-adapter.mdevent-system.mdindex.md
tile.json

tessl/npm-webcomponents--webcomponentsjs

A suite of polyfills supporting the Web Components specs including Custom Elements v1, Shadow DOM v1, HTMLTemplateElement, and platform polyfills

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@webcomponents/webcomponentsjs@2.8.x

To install, run

npx @tessl/cli install tessl/npm-webcomponents--webcomponentsjs@2.8.0

index.mddocs/

Web Components Polyfills

Web Components Polyfills is a comprehensive suite of polyfills that provides Web Components support for browsers that don't natively implement the specifications. It includes polyfills for Custom Elements v1, Shadow DOM v1, HTMLTemplateElement, and essential platform features like Promise, Event constructors, and DOM methods.

Package Information

  • Package Name: @webcomponents/webcomponentsjs
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @webcomponents/webcomponentsjs

Core Imports

Script Tags (Browser):

<!-- Dynamic loader (recommended) -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

<!-- Complete bundle -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>

<!-- ES5 adapter (when needed) -->
<script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>

CDN Usage:

<script src="https://unpkg.com/@webcomponents/webcomponentsjs@^2/webcomponents-loader.js"></script>

Basic Usage

Synchronous Loading (Simple):

<!-- Load polyfills synchronously -->
<script src="webcomponents-loader.js"></script>

<!-- Your custom elements can be loaded immediately -->
<script type="module" src="my-element.js"></script>

<!-- Use custom elements -->
<my-element></my-element>

Asynchronous Loading (Recommended):

<!-- Load polyfills asynchronously with defer -->
<script src="webcomponents-loader.js" defer></script>

<!-- Load custom elements after polyfills are ready -->
<script type="module">
  WebComponents.waitFor(() => {
    // Polyfills are guaranteed to be ready here
    return import('./my-element.js');
  });
</script>

<!-- Use custom elements -->
<my-element></my-element>

Architecture

The Web Components Polyfills package is built around several key components:

  • Dynamic Loader: Feature detection system that loads only necessary polyfills based on browser capabilities
  • Polyfill Bundles: Pre-compiled combinations of polyfills for different browser support scenarios
  • Platform Polyfills: Low-level JavaScript and DOM API polyfills for older browsers
  • Integration Layer: Global API for coordinating polyfill loading and custom element lifecycle
  • Trusted Types Support: CSP-compatible loading mechanism for security-conscious applications

Capabilities

Dynamic Polyfill Loading

Smart loader that detects browser capabilities and dynamically loads only the necessary polyfill bundles, optimizing performance by avoiding unnecessary code.

// Global WebComponents object available after loader runs
interface WebComponents {
  /** Indicates if polyfills are loaded and ready */
  ready: boolean;
  /** Optional root path for loading polyfill bundles */
  root?: string | TrustedScriptURL;
  /** Register callback to run after polyfills load (async loading only) */
  waitFor(callback: () => void | Promise<any>): void;
  /** Internal method for batching custom element upgrades */
  _batchCustomElements(): void;
}

declare global {
  interface Window {
    WebComponents: WebComponents;
  }
}

Dynamic Loading

Complete Polyfill Bundle

All-in-one bundle containing every Web Components polyfill, suitable for simple usage scenarios where loading optimization is not critical.

// No API - just include the script tag
// <script src="webcomponents-bundle.js"></script>
// All polyfills load immediately and Web Components APIs become available

Bundle Usage

ES5 Custom Elements Adapter

Compatibility layer that allows ES5-style custom element classes to work with native Custom Elements implementation when serving transpiled code to all browsers.

// No direct API - include before defining custom elements
// <script src="custom-elements-es5-adapter.js"></script>
// Automatically wraps ES5 classes for native Custom Elements compatibility

ES5 Adapter

Custom Event System

WebComponentsReady event system that signals when polyfills are loaded and custom elements are ready for use.

// WebComponentsReady event fired on document
interface WebComponentsReadyEvent extends CustomEvent {
  type: 'WebComponentsReady';
  bubbles: true;
}

// Event listener pattern
document.addEventListener('WebComponentsReady', () => {
  // Polyfills loaded, custom elements upgraded
});

Event System

Types

// Trusted Types support for CSP environments
type TrustedScriptURL = any; // Browser-specific type

// Callback function for waitFor
type WaitForCallback = () => void | Promise<any>;

// WebComponents global interface
interface WebComponents {
  ready: boolean;
  root?: string | TrustedScriptURL;
  waitFor(callback: WaitForCallback): void;
  _batchCustomElements(): void;
}