Filoaders

A beautiful, production-ready React component library for canvas-based loader animations.

Built with TypeScript, SOLID principles, and designed for maximum developer experience. 69 unique loaders with advanced customization features.

✨ Features

• 🎨 69 Beautiful Loaders - Diverse collection of canvas-based animations
• 📦 TypeScript First - Full type safety and IntelliSense support
• ⚡ Highly Performant - Optimized canvas rendering at 60fps
• 🎭 Fully Customizable - Control colors, size, speed, and more
• 🎯 Per-Dot Styling - Customize individual dots by position/index/time
• 🌈 Gradient Support - Linear and radial gradients for backgrounds and dots
• 🌓 Theme Detection - Auto-detect system/next-themes preferences
• 🎭 SVG Mask Support - Apply custom SVG masks to loaders
• 🔧 SOLID Principles - Clean, maintainable architecture
• 🌳 Tree-shakeable - Import only what you need
• 💅 Zero Runtime Dependencies - Only React as peer dependency
• 🎮 Interactive Playground - Configure and generate code visually

📦 Installation

npm install filoaders
# or
yarn add filoaders
# or
pnpm add filoaders

🚀 Quick Start

import { PulseWaveLoader } from 'filoaders';
import 'filoaders/styles.css';

function App() {
  return <PulseWaveLoader size={180} dotColor="#3b82f6" />;
}

🎨 Advanced Features

Per-Dot Styling

Customize individual dots based on position, index, and animation state:

import { PulseWaveLoader, rainbowDots } from 'filoaders';

// Use preset
<PulseWaveLoader dotStyle={rainbowDots} />

// Custom styling
<PulseWaveLoader
  dotStyle={({ index, time }) => ({
    color: `hsl(${index * 10}, 70%, 60%)`,
    opacity: 0.5 + Math.sin(time + index) * 0.5,
    size: 1 + Math.sin(time) * 0.3,
  })}
/>

Gradient Backgrounds

Apply beautiful gradients to backgrounds:

import { SpiralGalaxyLoader, gradientPresets } from 'filoaders';

// Use preset
<SpiralGalaxyLoader backgroundGradient={gradientPresets.sunset} />

// Custom gradient
<SpiralGalaxyLoader
  backgroundGradient={{
    type: 'radial',
    stops: [
      { offset: 0, color: '#1e3a8a' },
      { offset: 1, color: '#000000' },
    ],
  }}
/>

Theme Detection

Automatic theme detection with next-themes support:

<PulseWaveLoader
  theme={{
    mode: 'auto', // 'light' | 'dark' | 'auto'
    lightColors: {
      dotColor: '#000000',
      backgroundColor: '#ffffff',
    },
    darkColors: {
      dotColor: '#ffffff',
      backgroundColor: '#000000',
    },
  }}
/>

SVG Masks

Apply custom SVG masks for creative effects:

import { BreathingGridLoader, maskPresets } from 'filoaders';

// Use preset
<BreathingGridLoader mask={maskPresets.heart} />

// Custom SVG
<BreathingGridLoader
  mask={{
    svg: `<svg viewBox="0 0 100 100">
      <circle cx="50" cy="50" r="45" fill="white"/>
    </svg>`,
    scale: 0.9,
  }}
/>

Combined Features

Mix and match for stunning effects:

import {
  RadiatingScanLoader,
  rainbowDots,
  gradientPresets,
  maskPresets,
} from 'filoaders';

<RadiatingScanLoader
  size={220}
  dotStyle={rainbowDots}
  backgroundGradient={gradientPresets.sunset}
  mask={maskPresets.star}
  theme={{ mode: 'auto' }}
/>

📖 View Advanced Features Guide for complete documentation.

🎭 Available Loaders (69 Total)

All loaders share a common props interface for consistency. Here's a selection organized by category:

Wave & Pulse (12 loaders)

• PulseWaveLoader - Concentric dot rings with radial pulse
• PulseShockwaveLoader - Pulse wave with rotation effect
• InterwovenPulsesLoader - Independent ring pulses
• CircularWavesLoader - Circular wave propagation
• PendulumWaveLoader - Pendulum-inspired wave motion
• RippleEffectLoader - Water ripple simulation
• InterconnectingWavesLoader - Interwoven wave patterns
• SequentialPulseLoader - Sequential pulse animation
• RadialPulseLoader - Radial pulse effect
• PulsatingCirclesLoader - Pulsating circular rings
• PulseShockwaveLoader - Shockwave pulse effect
• PulsingGridLoader - Pulsing grid pattern

Spiral & Rotation (8 loaders)

• SpiralGalaxyLoader - Rotating spiral arms
• SpiralRadiatingLoader - Spiral with radiating pulse
• FibonacciSpiralLoader - Golden ratio spiral
• SilverSpiralLoader - Silver ratio spiral
• SunflowerSpiralLoader - Sunflower seed pattern
• RotatingOrbitsLoader - Rotating orbital paths
• ConcentricRotationsLoader - Concentric rotating rings
• OrbitalPulseLoader - Orbital pulse animation

Grid & Pattern (5 loaders)

• BreathingGridLoader - Grid with radial expansion
• PulsingGridLoader - Pulsing grid pattern
• InterferenceGridLoader - Wave interference pattern
• HalftoneGradientLoader - Halftone dot pattern
• VoronoiOrganicLoader - Voronoi diagram animation

3D & Geometric (12 loaders)

• SphereScanLoader - 3D sphere scan effect
• CrystallineRefractionLoader - Crystal refraction
• CrystallineCubeRefractionLoader - 3D cube refraction
• HelixScannerLoader - DNA helix scanner
• CylindricalAnalysisLoader - Cylindrical projection
• VoxelMatrixMorphLoader - Voxel matrix morphing
• TriAxialGimbalLoader - 3D gimbal rotation
• ScatterPlot3DLoader - 3D scatter plot
• PyramidDotLoader - Pyramid dot formation
• DNADoubleHelixLoader - DNA double helix
• TorusKnotFlowLoader - Torus knot topology
• Tesseract4DLoader - 4D hypercube projection

Mathematical & Physics (11 loaders)

• MobiusRibbonLoader - Möbius strip topology
• PolarLissajousLoader - Lissajous curves
• SphericalHarmonicsLoader - Spherical harmonics
• LorenzAttractorLoader - Lorenz attractor chaos
• QuasicrystalPenroseLoader - Penrose tiling
• KleinBottleLoader - Klein bottle topology
• QuantumOrbitalLoader - Quantum orbital patterns
• HopfFibrationLoader - Hopf fibration
• AiryDiskLoader - Airy disk diffraction
• NewtonsCraddleLoader - Newton's cradle physics
• DoublePendulumChaosLoader - Chaotic double pendulum

Organic & Natural (6 loaders)

• FlowingEnergyLoader - Flowing energy bands
• ReactionDiffusionLoader - Reaction-diffusion system
• BinaryTreeGrowthLoader - Binary tree growth
• VoronoiOrganicLoader - Organic Voronoi cells
• FerrofluidSpikesLoader - Ferrofluid spike simulation
• FluidOrbLoader - Fluid dynamics orb

Scan & Radar (5 loaders)

• RadiatingScanLoader - Rotating scan lines
• SonarSweepLoader - Sonar sweep effect
• PhasedArrayEmitterLoader - Phased array emission
• SphereScanLoader - Spherical scan

Rings & Circles (6 loaders)

• ConcentricRingsLoader - Concentric ring animation
• SequentialRingsLoader - Sequential ring appearance
• StretchedRingsLoader - Radially stretched rings
• ExpandingLinesLoader - Expanding line segments
• PulsatingCirclesLoader - Pulsating circles

Specialized (4 loaders)

• BouncingProgressBarLoader - Bouncing progress bar
• BouncingBarGraphLoader - Animated bar graph
• ECGHeartbeatLoader - ECG heartbeat monitor
• PlaceholderSkeletonLoader - Skeleton placeholder
• TripleBouncingDotsLoader - Three bouncing dots
• OscillatingDotsLoader - Oscillating dot pattern
• MandelbrotZoomLoader - Mandelbrot set zoom
• BlackHoleAccretionLoader - Black hole accretion disk

View the complete list with live demos in the Interactive Playground

📖 Common Props (BaseLoaderProps)

All loaders accept these props:

Basic Props

Advanced Props

See ADVANCED_FEATURES.md for detailed documentation on advanced props.

💡 Usage Examples

Basic Usage

import { PulseWaveLoader } from 'filoaders';
import 'filoaders/styles.css';

function LoadingScreen() {
  return (
    <div style={{ display: 'flex', justifyContent: 'center', padding: '50px' }}>
      <PulseWaveLoader />
    </div>
  );
}

Custom Colors

<PulseWaveLoader 
  size={200}
  dotColor="#3b82f6"
  backgroundColor="#000000"
/>

Custom Speed

<SpiralGalaxyLoader 
  animationSpeed={2}  // 2x speed
  size={180}
/>

Controlled Animation

function ControlledLoader() {
  const [paused, setPaused] = useState(false);

  return (
    <div>
      <button onClick={() => setPaused(!paused)}>
        {paused ? 'Resume' : 'Pause'}
      </button>
      <PulseWaveLoader paused={paused} />
    </div>
  );
}

Animation Callback

<PulseWaveLoader
  onAnimationFrame={(time) => {
    console.log(`Animation time: ${time}s`);
  }}
/>

Multiple Loaders

import {
  PulseWaveLoader,
  SpiralGalaxyLoader,
  BreathingGridLoader,
} from 'filoaders';

function LoaderShowcase() {
  return (
    <div style={{ display: 'flex', gap: '20px' }}>
      <PulseWaveLoader dotColor="#3b82f6" />
      <SpiralGalaxyLoader dotColor="#10b981" />
      <BreathingGridLoader dotColor="#ef4444" />
    </div>
  );
}

🏗️ Architecture

Filoaders is built with SOLID principles:

• Single Responsibility: Each loader handles one animation type
• Open/Closed: Extensible through props, closed for modification
• Liskov Substitution: All loaders are interchangeable via BaseLoaderProps
• Interface Segregation: Common interface with optional specific props
• Dependency Inversion: Components depend on abstractions (hooks/utils)

Project Structure

src/
├── types/                  # TypeScript interfaces
├── utils/                  # Shared utilities
│   ├── canvas.ts          # Canvas helpers
│   ├── colors.ts          # Color management
│   └── animation.ts       # Animation utilities
├── components/
│   ├── BaseLoader/        # Base animation hook
│   └── [LoaderName]/      # Individual loaders
└── index.ts               # Main exports

🛠️ Development

Setup

# Clone the repo
git clone https://github.com/your-org/filoaders.git
cd filoaders

# Install dependencies
yarn install

Development Commands

# Run demo app with Vite
yarn dev

# Launch Storybook
yarn storybook

# Build library for production
yarn build

# Build Storybook for deployment
yarn build-storybook

Demo App

The demo app (/demo) showcases all loaders with live controls:

• Adjust size, speed, opacity
• Change colors in real-time
• Pause/resume animations
• Test different configurations

Storybook

Interactive component documentation with:

• Individual loader stories
• Prop controls
• Color variants
• Usage examples

📄 TypeScript Support

Full TypeScript support with exported types:

import type { 
  BaseLoaderProps,
  PulseWaveLoaderProps,
  AnimationState,
  RingConfig,
} from 'filoaders';

const loaderProps: PulseWaveLoaderProps = {
  size: 180,
  dotColor: '#ffffff',
  animationSpeed: 1,
};

🎨 Customization

Custom Themes

const theme = {
  primary: '#3b82f6',
  secondary: '#8b5cf6',
  success: '#10b981',
  error: '#ef4444',
};

<PulseWaveLoader dotColor={theme.primary} />

Responsive Sizing

function ResponsiveLoader() {
  const size = useWindowSize();
  const loaderSize = size.width < 768 ? 120 : 180;

  return <PulseWaveLoader size={loaderSize} />;
}

📊 Performance

• Canvas-based rendering for smooth 60fps animations
• RequestAnimationFrame for optimal performance
• Automatic cleanup on unmount
• No layout thrashing - pure canvas operations

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines.

📝 License

MIT © [Your Name]

🔗 Links

• Demo
• Storybook
• NPM
• GitHub

Built with ❤️ using TypeScript, React, and Canvas API