@stackline/loading-core

Framework-agnostic TypeScript loading toolkit with spinners, overlays, skeletons, shimmer loaders, and smart anti-flicker behavior.

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

@stackline/loading-core is maintained as part of the Stackline package collection.

Compatibility

Installation

npm install @stackline/loading-core

Usage and API reference

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.4

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.2 preserves that stable runtime, CommonJS type resolution, and declaration compatibility with TypeScript 3.9 while updating package documentation and GitHub release tooling.

Features

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. Security
11. Community and Links
12. 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

Security

Report vulnerabilities privately by following SECURITY.md. Do not disclose exploit details in a public issue.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use the repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline to share examples, ask usage questions, and discuss releases.

License

MIT

Credits and original authors

• Alexandro Marques.
• Copyright (c) 2026 Alexandro Marques.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.