gradient-spin

A zero-dependency React matrix loading spinner — a grid of cells swept by a gradient wavefront. The cousin of a progress bar's shimmer: cells light up in arrow / diagonal / snake / ripple patterns, colored by a multi-stop gradient sampled in OKLab.

Live demo → gradient-spin.vercel.app · Sister library: gradient-shimmer (same gradient palettes, for text).

Why

• One CSS keyframe, compositor-only. Every cell shares a single opacity-only animation with a negative per-cell delay (delay = distance function over the grid). The spinner keeps ticking even while the main thread is busy with the work you're waiting for — exactly when a spinner matters.
• Steady-state mount. Negative delays mean the loop is already mid-flight on first paint: no fill-in ramp.
• Gradient-true cells. Colors are sampled from the gradient in OKLab (straight sRGB lerp detours through gray). Map it top→bottom like a backdrop (colorBy="row", the default) or give every cell a unique sample along the wave path (colorBy="path").
• No CSS import. Styles are injected once at runtime (useInsertionEffect, id-deduped). No Tailwind, no setup, zero runtime dependencies.
• Accessible. role="status" + aria-label; freezes to a static mid-state under prefers-reduced-motion.

Install

npm i gradient-spin

Usage

import { GradientSpin } from "gradient-spin"

// Defaults: 3×3, 4px cells, 750ms, "sunrise" gradient, arrow-up wave.
<GradientSpin />

// A chat feed's "loading older messages" strip:
<GradientSpin gradient="bay" pattern="snake" label="Loading older messages" />

// Custom gradient stops:
<GradientSpin
  gradient={[
    { color: "#B6D3EF", position: 0 },
    { color: "#F888A0", position: 1 },
  ]}
  rows={5}
  cols={7}
/>

Props

Prop	Type	Default
gradient	preset name | GradientStop[]	"sunrise"
pattern	"arrow-up" | "diagonal" | "snake" | "ripple"	"arrow-up"
rows	number	3
cols	number	3
cellSize	number (px)	4
cellGap	number (px)	2
cellRadius	number (px)	1
period	number (ms per sweep)	750
dim	number (0..1 resting opacity)	0.1
colorBy	"path" | "row"	"row"
label	string (aria-label)	"Loading"
respectReducedMotion	boolean	true

Plus any HTMLAttributes<HTMLSpanElement> — className, style, etc.

Presets (shared with gradient-shimmer): sunrise · bubble · peach · tonic · mint · spring · twilight · bay. Exported as gradientPresets; the OKLab sampler is exported as sampleGradient(stops, t).

How the patterns work

Each pattern is a distance function d(row, col); cells at equal distance form the wavefront, and a cell's animation delay is -(d / (max + 1)) × period:

• arrow-up — chevron fold across the center column: (rows−1−row) + |col−center|
• ripple — Chebyshev distance from the center (expanding square rings)
• diagonal & snake — travel patterns (anti-diagonal row + col; boustrophedon path from the bottom-left). Their distance is tiled into repeating bands (d % SCROLL_BAND) so the wave scrolls seamlessly and loops without teleporting from one corner back to the other.

Development

pnpm install
pnpm --dir site dev   # demo site at localhost:3021, aliased to library source
pnpm build            # tsup → dist (ESM + CJS + dts)
pnpm smoke:pack       # pack the tarball into a temp React 18 consumer

License

MIT © ziye