kil-loader

v1.0.4

Published

a month ago

Tiny zero-dependency page & AJAX loader that auto-injects CSS + DOM and tracks fetch/XHR/Axios.

0High
0Medium
0Low

kilvish

loader page-loader ajax spinner overlay fetch xhr axios

kil-loader

Zero-dependency page & AJAX loader that auto-injects its CSS + DOM, shows on first page load, and tracks fetch / XHR / Axios out of the box.

✅ No CSS file required
✅ Auto adds <div class="kil-main-loader">…</div> if missing
✅ Works without jQuery
✅ Tiny public API for manual control
✅ UMD build (works with <script>, ESM bundlers)

Install

npm i kil-loader

Bundlers

import KilLoader, { createKilLoader } from "kil-loader";

// (optional) customize BEFORE first use
KilLoader.config.backgroundAjax = "rgba(0,0,0,.06)";

// Next.js or manual control:
// const loader = createKilLoader({ autoShowOnPageLoad: false }, { autoInit: true });

CDN

Single script – no CSS tag required.

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

It auto-appears on first page load and around fetch/XHR/Axios calls.

In each project you have to put only cdn link and in common header following thing But if you dont put not issue becaue No markup needed—the script auto-inserts:

<div class="kil-main-loader" aria-busy="true" aria-live="polite">
  <span class="kil-page-loader"></span>
</div>

Quick Start

Nothing else required. The script injects its own DOM and CSS.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Kil Loader Demo</title>
    <script defer src="https://cdn.jsdelivr.net/npm/kil-loader@1/kil-loader.min.js"></script>
  </head>
  <body>
    <h1>Hello</h1>
  </body>
</html>

Optional config (still auto):

<script defer src="https://cdn.jsdelivr.net/npm/kil-loader@1/kil-loader.min.js"></script>
<script defer>
  KilLoader.config.borderColor   = "#ff1744";
  KilLoader.config.innerRingTint = "rgba(255, 77, 109, 0.55)";
  KilLoader.config.backgroundAjax = "transparent"; // or a tint if you want
</script>

Automatic Behavior

Page load overlay: shown until the window.load event.
Network overlay: shown while any fetch / XHR / Axios request is in flight.
Safety timeout: hides after 15s max if load never fires.
Scroll lock: prevents scroll while visible.

No initialization code is required for the CDN/UMD build or the default import.

Configuration

Set properties before first render for best effect.

KilLoader.config = {
  // timing
  pageSafetyTimeoutMs: 15000,
  fadeInMs: 120,
  fadeOutMs: 220,

  // visuals
  backgroundPage: "#ffffff",           // first page overlay background
  backgroundAjax: "transparent",       // ajax overlay background
  borderColor: "#2E37A4",              // spinner border
  innerRingTint: "rgba(46,55,164,.35)",

  // behavior
  autoTrack: true,                     // intercept fetch/XHR/Axios
  autoShowOnPageLoad: true,            // show on initial page load

  // classes / z-index
  classMain: "kil-main-loader",
  classSpinner: "kil-page-loader",
  lockScrollClass: "kil-lock-scroll",
  zIndex: 999999
};

You can also set individual keys:

KilLoader.config.backgroundAjax = "rgba(0,0,0,.06)";

Public API

KilLoader.show();         // show (mode="ajax")
KilLoader.show("page");   // force page mode
KilLoader.hide();         // hide (respects pending requests + load state)
KilLoader.destroy();      // remove DOM + injected styles

Use manual control if you run long CPU tasks (non-network) and want a visual indicator.

Optional HTML Markup

Not required. The script auto-injects if missing. Add it yourself only to control exact placement in the DOM.

<div class="kil-main-loader" aria-busy="true" aria-live="polite" data-mode="page">
  <span class="kil-page-loader"></span>
</div>

Disable Initial Overlay

Keep AJAX loader, skip first-page overlay:

<body data-kil-loader="off">
  ...
  <script defer src="https://cdn.jsdelivr.net/npm/kil-loader@1/kil-loader.min.js"></script>
</body>

Events

window.addEventListener("kil-loader:show", () => {
  // overlay became visible
});
window.addEventListener("kil-loader:hide", () => {
  // overlay fully hidden
});

Framework Tips

React / Next.js

// next/script with strategy="afterInteractive" or in _document.js
router.events.on("routeChangeStart", () => KilLoader.show());
router.events.on("routeChangeComplete", () => KilLoader.hide());
router.events.on("routeChangeError", () => KilLoader.hide());

Next.js (App Router)

Use Next's app/loading.tsx for route/server loading, and use kil-loader for client requests:

// app/loading.tsx
export default function Loading() {
  return <div className="kil-main-loader"><span className="kil-page-loader" /></div>;
}

// app/kil-loader-provider.tsx
"use client";
import { useEffect } from "react";
import { createKilLoader } from "kil-loader";

export function KilLoaderProvider() {
  useEffect(() => {
    const loader = createKilLoader({ autoShowOnPageLoad: false }, { autoInit: true });
    return () => loader.destroy();
  }, []);
  return null;
}

// app/layout.tsx
import { KilLoaderProvider } from "./kil-loader-provider";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <KilLoaderProvider />
        {children}
      </body>
    </html>
  );
}

Vue Router

router.beforeEach((to, from, next) => { KilLoader.show(); next(); });
router.afterEach(() => KilLoader.hide());

Plain JS (SPA)

The loader lightly hooks history.pushState/replaceState for a tiny flash on client navigation. You can also call KilLoader.show()/hide() around your custom transitions.

Accessibility

aria-busy="true" and aria-live="polite" on overlay
Locks scroll via body.kil-lock-scroll
Honors prefers-reduced-motion

SSR / Non-Browser

If window/document are unavailable, the module exports safe no-ops:

import KilLoader from "kil-loader";
KilLoader.show(); // does nothing on the server

Troubleshooting

Loader never hides on first load
Some assets may block the load event. The safety timer (default 15s) forces a hide:
```
KilLoader.config.pageSafetyTimeoutMs = 8000;
```
No overlay during AJAX
Ensure you use fetch, raw XMLHttpRequest, or axios. For custom clients, wrap with KilLoader.show()/hide().
Conflicts with other interceptors
If another lib patches fetch/XHR after kil-loader initializes, load kil-loader later or control manually.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

kil-loader

Table of Contents

Install

Bundlers

CDN

Quick Start

Automatic Behavior

Configuration

Public API

Optional HTML Markup

Disable Initial Overlay

Events

Framework Tips

Accessibility

SSR / Non-Browser

Troubleshooting

License