@stackline/loading-core

A maintained framework-agnostic loading toolkit for modern web applications, with polished variants, smart anti-flicker behavior, accessible defaults, and a documentation site with a live playground.

Documentation & Playground | npm | GitHub Download | Issues | Repository

Latest version: 1.0.1

Why this library?

Most loading packages stop at a basic spinner. Real products need more:

• multiple visual styles for cards, buttons, dashboards, tables, modals, and fullscreen states
• anti-flicker behavior so fast requests do not flash awkwardly
• accessible defaults with labels, role="status", aria-live, and reduced-motion support
• themeability through CSS variables without bringing a framework wrapper into the core package

@stackline/loading-core is built as a DOM-first TypeScript library that stays focused on the core runtime, so future framework wrappers can stay thin and consistent.

Version 1.0.1 preserves that stable runtime while refreshing the tested build chain, correcting CommonJS type resolution, and retaining declaration compatibility with TypeScript 3.9.

Features

| Feature | Supported | | :--- | :---: | | TypeScript-first core library | ✅ | | Framework-agnostic DOM runtime | ✅ | | ESM + CJS + bundled types | ✅ | | 35 built-in loading variants | ✅ | | Spinner, dots, bars, shimmer, skeleton, geometric, sports, and cosmic styles | ✅ | | Overlay, fullscreen, inline, and centered modes | ✅ | | Delay before show | ✅ | | Minimum visible duration | ✅ | | Mount, unmount, show, hide, toggle, and destroy lifecycle | ✅ | | Accessible labels and aria-live support | ✅ | | Reduced-motion support | ✅ | | CSS variable theming | ✅ | | Documentation site with live playground | ✅ | | Variant CSS injected on demand | ✅ |

Table of Contents

1. Installation
2. Direct Download
3. Quick Start
4. API Overview
5. Built-in Variants
6. Smart Loading Behavior
7. Accessibility and Theming
8. Documentation and Playground
9. Run Locally
10. License

Installation

npm install @stackline/loading-core

Direct Download

If you want to use the library in pure browser JavaScript, download the browser bundle from GitHub:

• GitHub downloads folder

The archive includes loading.browser.js and exposes window.StacklineLoading.

<section id="loader-host" style="min-height: 160px; position: relative;"></section>
<script src="./loading.browser.js"></script>
<script>
  const host = document.getElementById("loader-host");
  const loader = StacklineLoading.createLoader({
    variant: "orbit",
    overlay: true,
    centered: true,
    size: 48,
    label: "Loading analytics"
  });

  loader.mount(host);
  loader.show();
</script>

Quick Start

import { createLoader } from '@stackline/loading-core';

const panel = document.querySelector('.analytics-panel');

const loader = createLoader({
  variant: 'orbit',
  size: 48,
  color: '#2563eb',
  overlay: true,
  centered: true,
  delay: 150,
  minVisible: 280,
  label: 'Loading analytics'
});

loader.mount(panel);
loader.show();

try {
  await loadAnalytics();
} finally {
  await loader.hide();
  loader.destroy();
}

API Overview

The library is centered around a small public API:

import {
  createLoader,
  hideLoader,
  hydrateLoaders,
  mountLoader,
  showLoader
} from '@stackline/loading-core';

Core runtime capabilities:

• createLoader(options) creates a typed loader instance
• loader.mount(target) mounts into a container or fullscreen target
• loader.show() and loader.hide() respect delay and minVisible
• loader.update() lets you change variant, colors, sizing, or mode at runtime
• loader.destroy() removes the instance cleanly
• hydrateLoaders() enables declarative DOM usage through data-* attributes

Built-in Variants

The package currently ships 35 variants:

• ring, dual-ring, segmented-ring, arc, orbit, comet, halo, radar
• astronaut, astronaut-to-mars, baseball-player, football-player, galaxy
• pulse, wave-dots, bouncing-dots, typing-dots, grid-pulse, magnetic-dots, spiral-dots, constellation
• equalizer-bars, rising-bars
• shimmer, scan-line, liquid-pill, ripple-stack, minimal-spinner, neon-spinner, glass-spinner
• vortex, cube, diamond, prism, skeleton-blocks

Smart Loading Behavior

The toolkit is designed for real application behavior, not just decoration.

• delay prevents flashing loaders for very fast requests
• minVisible avoids abrupt hide/show flicker once the loader appears
• overlay, fullscreen, inline, and centered cover common product layouts
• runtime mounting makes it easy to load cards, sections, buttons, tables, modals, and full pages

Example:

const loader = createLoader({
  variant: 'ring',
  delay: 180,
  minVisible: 320,
  overlay: true,
  centered: true,
  label: 'Syncing dashboard'
});

Accessibility and Theming

Accessibility is part of the default behavior:

• role="status" and aria-live support
• optional visible labels
• label: '' for compact cases where visible text should be removed
• reduced-motion support via prefers-reduced-motion

Theming is handled with CSS variables and exported theme tokens, so branded overrides stay straightforward.

Documentation and Playground

The docs site includes:

• installation and quick start guides
• API reference
• variants gallery
• theming and accessibility guides
• overlay, button, fullscreen, and container loading examples
• delay and minimum visibility guidance
• a live playground for variant, size, speed, color, and behavior testing

Docs: https://alexandro.net/docs/vanilla/loading/

Run Locally

npm install
npm run dev

Production build:

npm run build

Verification:

npm run typecheck
npm test

License

MIT