⚡ AtomLoader

Lightweight, customizable CSS-animated dot-matrix loading indicators for React and Next.js.

500+ handcrafted, visually distinct geometric loading animations built with pure CSS grid and keyframes — zero heavy dependencies, SSR-safe, fully accessible, and styled with modern design tokens.

✨ Features

  • 500+ Genuinely Unique Loaders: Handcrafted patterns across 50 geometric families (Dot, Grid, Square, Circle, Ring, Hex, Triangle, Diamond, Star, Cross, Wave, Orbit, Spiral, Ripple, Burst, Matrix, DNA, Vortex, and Abstract).
  • Pure CSS Animations: Powered exclusively by CSS Grid and keyframe transforms. No GSAP, no Framer Motion, no Canvas, no WebGL.
  • shadcn CLI Native: Install any loader directly into your project as zero-dependency React components using the official shadcn CLI.
  • Ultra Scalable: Scales smoothly from 16px, 20px, 24px micro-indicators up to 64px+ hero loaders.
  • Multi-Stop Gradients & Bloom: Built-in linear and multi-stop gradient color interpolation with optional ambient bloom glow.
  • Accessible & SSR Safe: Includes @media (prefers-reduced-motion: reduce) motion dampening and full hydration safety.
  • TypeScript First: Strict types for pattern names, gradient configurations, and component props.

📦 Quick Installation

Option 1: Add via shadcn CLI (Recommended)

AtomLoader distributes components as direct shadcn UI registry items.

1. Configure the @atomloader registry namespace (once):

bash
# pnpmpnpm dlx shadcn@latest registry add "@atomloader=https://atomloader.roothq.tech/r/{name}.json"
# npmnpx shadcn@latest registry add "@atomloader=https://atomloader.roothq.tech/r/{name}.json"
# bunbunx --bun shadcn@latest registry add "@atomloader=https://atomloader.roothq.tech/r/{name}.json"

2. Install any specific loader:

bash
# Install individual standalone componentpnpm dlx shadcn@latest add @atomloader/diamond-orbit-smooth-loader# ornpx shadcn@latest add @atomloader/hex-perimeter-orbit-loader# or universal catalog componentnpx shadcn@latest add @atomloader/atom-loader

🚀 Usage

1. Standalone Loader Component

tsx
import { DiamondOrbitSmoothLoader } from "@/components/ui/diamond-orbit-smooth-loader";
export default function LoadingPage() {  return (    <div className="flex items-center justify-center min-h-[50vh]">      <DiamondOrbitSmoothLoader        dotSize={5}        gap={4}        speed={1.2}        color="#3b82f6"        bloom={true}      />    </div>  );}

2. Multi-Stop Gradient Customization

tsx
import { HexPerimeterOrbitLoader } from "@/components/ui/hex-perimeter-orbit-loader";
export default function GradientLoader() {  return (    <HexPerimeterOrbitLoader      dotSize={6}      gap={4}      speed={1.4}      gradient={{        from: "#3b82f6",        via: "#a855f7",        to: "#ec4899",        direction: "diagonal",      }}      bloom={true}    />  );}

3. Universal AtomLoader Component

tsx
import { AtomLoader } from "@/components/ui/atom-loader";
export default function UniversalLoader() {  return (    <AtomLoader      pattern="vortex-angular-spin"      dotSize={5}      gap={3}      speed={1.0}      color="currentColor"    />  );}

⚙️ Component API

All loaders accept the following props:

PropTypeDefaultDescription
dotSizenumber5Size of each dot in pixels
gapnumber4Spacing between dots in pixels
speednumber1.2Duration of one full animation cycle (seconds)
colorstring"currentColor"Active dot color (#hex, rgb(), currentColor)
gradientGradientConfigundefinedOptional multi-stop gradient configuration
bloombooleanfalseEnable soft ambient glow bloom filter
opacitynumber0.08Opacity of inactive grid nodes (0 to 1)
classNamestring""Additional custom CSS class names

GradientConfig

typescript
interface GradientConfig {  from: string;  via?: string;  to: string;  direction?: "diagonal" | "horizontal" | "vertical";}

🧬 Motion Engine Architecture

AtomLoader operates on 19 discrete CSS animation keyframe models mapped dynamically to matrix nodes:

  1. dot-orbit: Smooth planetary rotational flow.
  2. dot-wave: Sinusoidal amplitude wavefronts.
  3. dot-breathe: Harmonic expansion and luminescence cycles.
  4. dot-pop: Sharp staccato impulses.
  5. dot-flicker: Randomized celestial micro-sparkles.
  6. dot-leapfrog: Synchronized alternating node hops.
  7. dot-collapse: Inward gravitational singularity compression.
  8. dot-burst: Outward radial explosive shockwaves.
  9. dot-iris: Camera aperture dilation and contraction.
  10. dot-snake: Continuous serpentine corridor traversal.
  11. dot-counterflow: Opposing phase counter-rotational shear.
  12. dot-radar: 360-degree sweeping sonar sectors.
  13. dot-magnet: Elastic focal attraction and recoil.
  14. dot-dna: Intertwined helical phase oscillation.
  15. dot-vortex: Accelerating angular vortex sink.
  16. dot-stair: Quantized discrete step descents.
  17. dot-checker: Antiphase binary square wave swap.
  18. dot-glitch: High-frequency digital phase jitter.
  19. dot-scan: Linear raster laser scanlines.

🛠 Local Development

bash
# Clone the repositorygit clone https://github.com/HimanshuTamoli24/loader.gitcd loader
# Install dependenciespnpm install
# Generate loaders & build registrypnpm run build:registry
# Start the development serverpnpm dev

📄 License

MIT ©