loadersz
Framework-agnostic, dependency-free Canvas loaders for the browser. loadersz ships as a native Web Component and a small imperative TypeScript API-no React, SVG filters, or runtime dependencies.
150 motion states. One fixed state is 2.5–3.1 kB gzipped; the complete switchable library is available from one import.
Install
npm install loadersz
Enumerate available states
Use the tiny, side-effect-free states entry when building a picker or documentation UI:
import { LOADER_STATES } from "loadersz/states";
console.log(LOADER_STATES); // ["working", "searching", …]
Use the category metadata when building a picker or gallery. It keeps product-style loaders,
loaders, systems, data & telemetry, reasoning, atmosphere and motion studies in the same order as the official website:
import { LOADER_CATEGORIES } from "loadersz/states";
for (const category of LOADER_CATEGORIES) {
console.log(category.label, category.states);
}
Import once in your application to register the custom element safely:
import "loadersz";
Custom element
<loadersz-loader
state="calibrating"
size="144"
speed="1.15"
density="1"
theme="dark"
aria-label="Calibrating"
></loadersz-loader>
size is required in practice: it is the square canvas side in CSS pixels. Use 64 for a compact status indicator, 144 for a card, or 280 for a hero-sized loader.
Attributes
| Attribute |
Type |
Default |
Description |
state |
state name |
working |
Selects the visual geometry. |
size |
number |
96 |
Square side in CSS pixels; values below 16 are clamped. |
speed |
number |
1 |
Timeline multiplier. |
density |
number |
1 |
Geometry detail; clamped to 0.35–2. |
particle-radius |
number |
1 |
Multiplies visible particle thickness; clamped to 0.5–2.5. |
theme |
auto, dark, light |
auto |
Canvas colour scheme. |
hue |
0–360 |
unset |
Overrides a mode's native colour palette. |
color |
CSS colour string |
unset |
Overrides hue; accepts hex, CSS colours, and var(--token). |
paused |
boolean attribute |
unset |
Stops frame scheduling and keeps the current frame visible. |
force-motion |
boolean attribute |
unset |
Overrides a reduced-motion preference; use only when appropriate. |
aria-label |
string |
Loading |
Accessible label applied to the internal canvas. |
Colour modes
Omit both hue and color to preserve the loader's native treatment. That can be a multi-colour palette or deliberately monochrome grey, depending on the movement. Set hue to recolour every visible particle with one hue, or set color for one exact CSS colour. color takes precedence over hue.
States
working, searching, connecting, weaving, shaping, listening, breathing, composing, solving, observing, dreaming, charging, flowing, awakening, coding, transcending, singing, growing, blooming, wandering, decoding, calibrating, attracting, shattering, crystallizing, constellating, folding, echoing, balancing, weathering, mapping, forging, orbiting, racing, bubbling, spinning, electrifying, flocking, throbbing, cascading, spiraling, juggling, eclipsing, resonating, condensing, dispersing, prisming, levitating, synchronizing, unraveling, pondering, deducing, branching, focusing, reflecting, weighing, recalling, tracing, converging, questioning, glimmering, radiating, harmonizing, twinkling, flickering, shimmering, surfacing, vibrating, illuminating, sparkling, loading, buffering, typing, processing, synthesizing, considering, uploading, queuing, associating, evaluating, reasoning, exploring, linking, resolving, and imagining.
Framework adapters
The core package remains a native Web Component. Typed adapters are available for the three frameworks that need framework-specific TypeScript or component integration.
React
import { LoaderszLoader } from "loadersz/react";
export function Status() {
return (
<LoaderszLoader
state="racing"
size={144}
speed={1.2}
ariaLabel="Loading results"
/>
);
}
Importing loadersz/react also adds type support for direct custom-element JSX:
import "loadersz/react";
const loader = <loadersz-loader state="orbiting" size={96} />;
Vue 3
<script setup lang="ts">
import { LoaderszLoader } from "loadersz/vue";
</script>
<template>
<LoaderszLoader
state="bubbling"
:size="144"
:speed="1.1"
aria-label="Loading"
/>
</template>
Svelte 4 and 5
<script lang="ts">
import 'loadersz/svelte';
</script>
<loadersz-loader state="spiraling" size={144} aria-label="Loading" />
Angular
Use the standalone Angular directive. It makes the native element known to Angular and adds typed bindings without CUSTOM_ELEMENTS_SCHEMA. The runtime import is intentionally explicit, so the same pattern works with a small direct state import. Keep the loader in normal HTML — never inside an <svg> or <defs> block.
import { Component } from "@angular/core";
import "loadersz";
import { LoaderszLoader } from "loadersz/angular";
@Component({
standalone: true,
selector: "app-root",
imports: [LoaderszLoader],
template: `
<loadersz-loader
[state]="state"
[size]="144"
aria-label="Loading"
></loadersz-loader>
`,
})
export class App {
readonly state = "racing" as const;
}
For Solid, Qwik, Lit, and plain HTML, import loadersz and use <loadersz-loader> directly.
Which import should I use?
| Framework |
Loader can change at runtime |
One fixed loader |
| React |
import { LoaderszLoader } from 'loadersz/react' |
import 'loadersz/racing' plus React's type-only import below |
| Vue 3 |
import { LoaderszLoader } from 'loadersz/vue' |
import 'loadersz/racing' and use the native element |
| Svelte |
import 'loadersz/svelte' |
import 'loadersz/racing' plus import type {} from 'loadersz/svelte' |
| Angular |
import 'loadersz' + LoaderszLoader |
import 'loadersz/racing' + LoaderszLoader |
| Lit, Solid, Qwik, HTML |
import 'loadersz' |
import 'loadersz/racing' |
The controls are always the same. The native element spells its multi-word attributes as aria-label, force-motion, and particle-radius; React and Vue wrappers spell them as ariaLabel, forceMotion, and particleRadius. state, size, speed, density, hue, color, theme, and paused keep the same name.
Single-mode imports
When a loader will never change state, use its direct entry point. It includes the Canvas core and exactly one geometry builder-no tree-shaking configuration required.
import "loadersz/racing";
<loadersz-loader
state="racing"
size="144"
speed="1.15"
aria-label="Loading results"
></loadersz-loader>
The direct entry's visual state is fixed by its import. The state attribute is accepted so markup stays familiar, but cannot load the other 84 animations. Every state name has a matching entry point: loadersz/working, loadersz/solving, loadersz/racing, and so on.
In React, a direct entry can stay small too. Import the fixed runtime entry and the adapter types only; TypeScript removes the type-only import from the browser bundle.
import "loadersz/racing";
import type { LoaderszReactProps } from "loadersz/react";
const loaderProps = { state: "racing", size: 96 } satisfies LoaderszReactProps;
export function Loading() {
return <loadersz-loader {...loaderProps} aria-label="Loading" />;
}
The direct import itself is framework-agnostic: it always registers the same native element and supports the same state, size, speed, density, hue, color, theme, paused, and force-motion attributes. Framework wrapper types are intentionally specific to their framework: use LoaderszReactProps for React, loadersz/vue for the typed Vue component, and import type {} from 'loadersz/svelte' alongside a direct entry for Svelte template typing. The Vue wrapper imports the complete switchable component, so use the native element when the smallest single-state bundle matters.
For a fixed canvas you own yourself, the same entry point exposes a fixed imperative controller:
import { LoaderszLoader } from "loadersz/racing";
const canvas = document.querySelector<HTMLCanvasElement>("#loading");
if (!canvas) throw new Error("Missing canvas");
const loader = new LoaderszLoader(canvas, {
size: 144,
speed: 1.15,
ariaLabel: "Loading results",
});
Use the root import when a component must change between states at runtime:
import "loadersz";
loadersz/modes remains available for applications that want named fixed-mode factories and already rely on an ESM-aware production bundler:
import { racing } from "loadersz/modes";
const canvas = document.querySelector<HTMLCanvasElement>("#loading");
if (!canvas) throw new Error("Missing canvas");
const loader = racing(canvas, {
size: 144,
speed: 1.15,
ariaLabel: "Loading results",
});
The returned controller still supports setOptions, paused, colour, speed, density, and destroy(). Its visual mode is fixed to the imported factory.
Imperative API
Use the imperative API when your application owns a canvas or controls the lifecycle directly.
import { LoaderszLoader } from "loadersz";
const canvas = document.querySelector<HTMLCanvasElement>("#loader");
if (!canvas) throw new Error("Missing canvas");
const loader = new LoaderszLoader(canvas, {
state: "solving",
size: 160,
speed: 1.1,
theme: "dark",
ariaLabel: "Solving",
});
loader.setOptions({ state: "forging", size: 200, hue: 28 });
loader.destroy();
All exported types and methods include TSDoc, so editors show parameter descriptions, defaults, return values, and lifecycle behaviour on hover.
- Respects
prefers-reduced-motion by default and pauses in hidden tabs.
- Canvas device-pixel ratio is capped at
2 to avoid excessive bitmap work.
- The core has zero regular runtime dependencies. React, Vue, and Svelte are optional peer dependencies and are only needed when importing their adapter entry point.
- Use a meaningful
aria-label for non-decorative loaders. Use aria-hidden="true" on a decorative surrounding element where appropriate.
Development
Install dependencies and enable the local Git hooks once:
npm install
npm run hooks:install
Commits follow Conventional Commits. Pre-commit checks format and lint staged files. The release package intentionally contains no install lifecycle scripts.
Browser benchmark UI
Start the interactive production-build benchmark:
npm run benchmark:ui
Open http://127.0.0.1:4174, choose a scenario, and select Run benchmark. Stop the local server with Ctrl+C. See BENCHMARKING.md for A/B comparisons, equivalence checks, CI behaviour, and measurement rules.
License
MIT © 2026 lumberjacque.
loadersz 是一个零依赖的浏览器 Canvas 加载动画库，以原生 Web Component 的形式发布，配有精简的命令式 TypeScript API 和 150 种可切换的动效状态。