Web Component Loader

Utility for lazy-loading web components.

Web Component Loader uses the IntersectionObserver API to defer loading components until they enter the viewport. It also uses the MutationObserver API to observe the DOM for newly inserted components. This allows to dynamically insert components into the DOM and have them loaded automatically.

• 📦 small: 1.5kb minified
• 🚀 fast: Uses IntersectionObserver to defer loading components
• 🧩 flexible: Provides a class and a function for loading components
• 🎨 customizable: Define various options for loading components

Setup

npm install @somehow-digital/web-component-loader

Usage

Web Component Loader provides a class and a function for loading components. The utility function is a wrapper around the class. The class is more flexible, but the function is more convenient.

Class

The class is a wrapper around the customElements.define function. It allows you to define components and then run the loader. This is useful if you want to define components in one place and then run the loader in another.

import Loader from '@somehow-digital/web-component-loader';

const loader = new Loader(/* options */);
loader.register('component-one', () => import('component-one.js'));
loader.register('component-two', () => import('component-two.js'), /* options */);

Function

The function returns a function that can be called to run the loader. This is useful to run the loader independently of the component definitions.

import { register } from '@somehow-digital/web-component-loader';

register({
  'component-one': () => import('component-one.js'),
  'component-two': [() => import('component-two.js'), /* options */],
})(/* options */);

Options

Options can be passed to the register function or the Loader class. Options can be set globally or some can be set per component definition. See file loader.ts for the default values.

| Option | Type | Default | Global | Element | Description | |--------------|---------------|------------|:------:|:-------:|---------------------------------------------------------------| | context | HTMLElement | document | ✅ | | The DOM context to search for components in. | | init | boolean | true | ✅ | | Whether to run the loader immediately. | | contextual | boolean | true | ✅ | ✅ | Whether to load components found in the DOM context. | | defer | boolean | true | ✅ | ✅ | Whether to defer loading components on entering the viewport. | | observe | boolean | true | ✅ | | Whether to observe the DOM for newly inserted components. | | define | boolean | true | ✅ | ✅ | Whether to define components when loading them. | | margin | string | 0px | ✅ | | The margin used when loading deferred elements. | | selector | function | ... | ✅ | ✅ | Selector to use when searching for components. | | excludes | string[] | [...] | ✅ | | An array of element names to exclude from processing. |

somehow.digital