Lazy Loader

A lightweight (~2kb) Web Component based lazy loading library.

Install

Install via NPM:

npm i -S @codewithkyle/lazy-loader

Or via CDN:

import { configure, update, mount, css } from "https://cdn.jsdelivr.net/npm/@codewithkyle/lazy-loader@1/lazy-loader.min.mjs";

<script src="https://cdn.jsdelivr.net/npm/@codewithkyle/lazy-loader@1/lazy-loader.min.js">

Usage

ES Module

import { configure, update, mount, css } from "https://cdn.jsdelivr.net/npm/@codewithkyle/lazy-loader@1/lazy-loader.min.mjs";

// Start the lazy loading process by configuring the default locations for your JS and CSS files
configure({
    jsDir: "/js",
    cssDir: "/css",
    default: "lazy", // optional
    lazierCSS: false, // optional
});

// Alternatively if the default settings (seen above) are okay you could simply call the update function instead
// You can call the update function at any time
update();

// Manually mount new components
import { MyCustomElement } from "./my-custom-element.js";
mount("my-custom-element", MyCustomElement); // returns a promise

// Alternatively if the components file name matches the tag name the library can dynamically import the script from the JS directory (see configure function)
mount("my-custom-element");

// Manually lazy load CSS files
css("exmaple.css"); // returns a promise

// Alternatively you can load multiple files at once
css(["example-one", "examle-two.css", "https://cdn.example.com/example-two.css", "../../relative-path-example.css"]);

Common JS

LazyLoader.configure({
    jsDir: "/",
    cssDir: "/",
    default: "lazy", // optional
    lazierCSS: false, // optional
});
LazyLoader.update();
LazyLoader.mount("my-custom-element")

Interfaces

type Loading = "eager" | "lazy";

interface LazyLoaderSettings {
    cssDir?: string;
    jsDir?: string;
    default?: Loading;
    lazierCSS: boolean;
};

declare const configure: (settings?:Partial<LazyLoaderSettings>) => void;
declare const update: () => void;
declare const mount: (tagName:string, constructor?: CustomElementConstructor) => Promise<void>;
declare const css: (files:string|string[]) => Promise<void>;

HTML Attributes

<!-- Lazy load Web Components by tagging custom elements with the web-component attribute. -->
<!-- In this example the custom-element.js file will be imported from the configured jsDir directory. -->
<custom-element web-component></custom-element>

<!-- You can override the default import behavior by providing a custom file name, relative path, or a URL. -->
<custom-element web-component="custom-file-name.js"></custom-element>

<!-- By default components are loaded and mounted when they enter the viewport. -->
<!-- You can bypass the lazy loader by using the loading attribute. -->
<custom-element web-component loading="eager"></custom-element>

<!-- You can lazy load CSS by attaching the css attribute to any element within the documents body. -->
<!-- You can load multiple files using a whitespace separator. Note that the .css file extenstion is optional. -->
<div class="my-awesome-class" css="awesome-transitions awesome.css"></div>