skeleton-lite

Headless skeleton-loading-state helper: delays showing a loading skeleton to avoid flicker on fast loads, and enforces a minimum display time once shown to avoid a jarring flash. No rendering — just the timing state machine, wire it to any UI.

Install

npm install skeleton-lite

Quick start

import { SkeletonController } from 'skeleton-lite';

const skeleton = new SkeletonController({ delayMs: 200, minDurationMs: 300 });
skeleton.subscribe((visible) => setSkeletonVisible(visible));

async function loadData() {
  skeleton.start();
  try {
    return await fetchData();
  } finally {
    skeleton.stop();
  }
}

Why the two timing rules

Showing a skeleton the instant loading starts makes fast, sub-200ms loads look like they flickered — the skeleton flashes on and off before a user can register it as anything but a glitch. The fix is a show delay: only render the skeleton if loading is still in progress after delayMs. But that alone creates a new problem — a load that takes just over the delay shows a skeleton for a few milliseconds before disappearing, another kind of flash. The minimum duration rule fixes that: once shown, the skeleton stays for at least minDurationMs regardless of when the real data actually arrives.

API

• new SkeletonController({ delayMs?, minDurationMs?, ... })
• .start() / .stop() — call around your loading operation
• .isVisible() — current visibility
• .subscribe(listener) — returns an unsubscribe function

setTimeoutFn/clearTimeoutFn/now are injectable for deterministic tests.

License

MIT