Documentation

A small API for motion states.

Pick the import that matches your UI, then use the same small set of controls everywhere.

Install

One package.

npm install loadersz

Custom element

Works in any frontend.

Import the package once to register the element. Use a meaningful label whenever the loader conveys status.

import 'loadersz';

<loadersz-loader
  state="solving"
  size="96"
  speed="1.1"
  aria-label="Solving"
></loadersz-loader>

Framework guide

Choose a framework. Then choose an import.

Use the full import when the animation can change at runtime. Use a direct import when it is fixed: that ships one movement and the canvas core.

State can change

Import the full entry or framework adapter. Set any of the 70 states.

State is fixed

Import one state such as loadersz/racing. Smaller bundle, same element.

Use the full library when the state can change while the app runs.

import 'loadersz';

<loadersz-loader state="racing" size="96" aria-label="Loading"></loadersz-loader>

Smaller application bundles

Import one fixed movement.

A direct state entry includes the Canvas core and exactly one animation. It needs no bundler configuration and registers the same native element.

import 'loadersz/racing';

<loadersz-loader
  state="racing"
  size="96"
  aria-label="Loading"
></loadersz-loader>

Use loadersz/racing, loadersz/solving, or any of the 70 state names. Each fixed entry currently ships at roughly 2.5–3.1 kB gzipped. Use loadersz when you need to switch states at runtime.

For an owned canvas, import LoaderszLoader from the same direct entry. loadersz/modes remains available for named factories in ESM-aware builds.

A direct import fixes the drawing code, not the markup. Keep the matching state value in your markup for clarity, but changing it later does not load another animation.

Prop names

Same controls. Two spellings.

The native element uses browser attribute names. React and Vue wrappers use camelCase only for the two multi-word props; every other control keeps its name.

Native elementReact / Vue wrapperMeaning

aria-labelariaLabelAccessible label

force-motionforceMotionIgnore reduced motion

size, speed, density, hue, color, themesame namesVisual controls

pausedpausedFreeze the current frame

Attributes

The controls.

stateworking

The semantic movement to show.

size96

Square canvas size in CSS pixels.

speed1

Animation timeline multiplier.

density1

Geometry detail from 0.35 to 2.

hue-

A hue from 0 to 360. Omit it for the native palette.

color-

A hex, CSS colour, or inherited CSS variable. Overrides hue.

themeauto

auto, dark, or light.

pausedfalse

Stops on the current frame when present.

force-motionfalse

Keeps animating when reduced motion is enabled.

Leave both hue and color off to preserve the motion’s own palette. That includes multicolour treatments and deliberately monochrome loaders. Add hue for one unified hue or color for one exact CSS colour.

<!-- Native: preserves the motion's own palette -->
<loadersz-loader state="racing" size="96" />

<!-- Hue: one unified colour -->
<loadersz-loader state="racing" size="96" hue="278" />

<!-- CSS: one exact colour or a CSS token -->
<loadersz-loader state="racing" size="96" color="var(--brand)" />