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

Prop	Type	Default	Description
size	number	180	Canvas size in pixels
animationSpeed	number	1	Animation speed multiplier (0.1-3)
dotColor	string	'#ffffff'	Primary color for dots/elements
backgroundColor	string	'transparent'	Canvas background color
className	string	''	Additional CSS classes
opacity	number	1	Global opacity (0-1)
paused	boolean	false	Pause the animation
onAnimationFrame	(time: number) => void	undefined	Callback on each frame

Advanced Props

Prop	Type	Default	Description
dotStyle	DotStyleFunction	undefined	Function to customize individual dots
dotGradientConfig	GradientConfig	undefined	Gradient configuration for dots
backgroundGradient	GradientConfig	undefined	Gradient configuration for background
theme	ThemeConfig	undefined	Theme detection and color switching
mask	SVGMaskConfig	undefined	SVG mask to apply to the loader

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