PerlinDOM

A lightweight JavaScript library for creating smooth, organic animations on DOM elements using Perlin noise. Create natural, fluid movements that bring your web interfaces to life.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Examples
• Best Practices
• API Reference
• Troubleshooting
• Browser Compatibility
• Changelog
• License

✨ Features

• 🌊 Organic Animations: Natural movements using Perlin noise that avoid mechanical rigidity
• 📱 Responsive Design: Support for percentage-based values that adapt to container size
• 🎯 Smart Positioning: Automatically works from element's current position (CSS or inline styles)
• ⚡ High Performance: Uses transform and requestAnimationFrame for smooth 60fps animations
• 🎛️ Full Control: Play, pause, and destroy animations with smooth transitions
• 📦 Lightweight: Minimal footprint with zero dependencies
• 🔧 Easy Integration: Simple API that works with any DOM element
• 🎨 Flexible: Mix pixel and percentage values, animate on single or both axes

📦 Installation

npm install @andresclua/perlindom

Or include directly in your HTML:

<script type="module">
  import PerlinDOM from 'https://unpkg.com/@andresclua/perlindom/dist/perlindom.es.js';
</script>

🚀 Quick Start

import PerlinDOM from '@andresclua/perlindom';

// Basic animation - element will animate from its current position
const animation = new PerlinDOM({
  element: document.querySelector('.my-element'),
  x: { min: -50, max: 50 },  // Move ±50px horizontally
  y: { min: -30, max: 30 },  // Move ±30px vertically
  speed: 0.01,               // Animation speed
  seed: 123                  // Reproducible pattern
});

// Control the animation
animation.pause();  // Smooth pause
animation.play();   // Resume
animation.destroy(); // Clean up

/* Your element needs positioning for transforms to work */
.my-element {
  position: relative; /* or absolute, or fixed */
  /* PerlinDOM will animate from wherever this element is positioned */
}

⚙️ Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | element | HTMLElement | required | The DOM element to animate | | x | Object \| null | null | Horizontal movement: {min: number, max: number} | | y | Object \| null | null | Vertical movement: {min: number, max: number} | | speed | number | 0.01 | Animation speed (lower = slower) | | seed | number | 0 | Seed for reproducible patterns | | lerpSpeed | number | 0.1 | Transition smoothness for pause/play |

Value Types

• Pixels: { min: -50, max: 50 } - Fixed pixel movement
• Percentages: { min: '-10%', max: '10%' } - Responsive to parent size
• Mixed: x: { min: '-5%', max: '5%' }, y: { min: -20, max: 20 }
• Single Axis: Set unused axis to null

📚 Examples

1. Basic Element Animation

<div class="floating-card">Content</div>

.floating-card {
  position: relative;
  left: 50%;
  top: 50%;
  transform: translate(-50%, -50%);
}

new PerlinDOM({
  element: document.querySelector('.floating-card'),
  x: { min: -20, max: 20 },
  y: { min: -15, max: 15 },
  speed: 0.008,
  seed: 42
});

2. Responsive Background Elements

// Elements adapt to container size changes
document.querySelectorAll('.bg-particle').forEach((el, index) => {
  new PerlinDOM({
    element: el,
    x: { min: '-15%', max: '15%' },  // 15% of parent width
    y: { min: '-10%', max: '10%' },  // 10% of parent height
    speed: 0.003,
    seed: index * 1000
  });
});

3. Interactive Hover Effects

const button = document.querySelector('.animated-button');
let animation;

button.addEventListener('mouseenter', () => {
  animation = new PerlinDOM({
    element: button.querySelector('.effect'),
    x: { min: -5, max: 5 },
    y: { min: -5, max: 5 },
    speed: 0.02,
    lerpSpeed: 0.15
  });
});

button.addEventListener('mouseleave', () => {
  animation?.pause();
});

4. Multiple Elements with Synchronized Patterns

// Same seed = synchronized movement
document.querySelectorAll('.sync-element').forEach(el => {
  new PerlinDOM({
    element: el,
    x: { min: -30, max: 30 },
    y: { min: -30, max: 30 },
    speed: 0.01,
    seed: 12345  // Same seed for all elements
  });
});

5. Custom Animation Patterns

// Horizontal-only movement for sliding effects
new PerlinDOM({
  element: document.querySelector('.slider'),
  x: { min: -100, max: 100 },
  y: null,  // No vertical movement
  speed: 0.005
});

// Vertical-only for floating effects
new PerlinDOM({
  element: document.querySelector('.floater'),
  x: null,  // No horizontal movement
  y: { min: -40, max: 40 },
  speed: 0.008
});

6. Advanced: SVG Path Animation

// Animate SVG elements or paths
const svgElement = document.querySelector('#animated-path');
const pathAnimation = new PerlinDOM({
  element: null,  // No direct element
  x: { min: -20, max: 20 },
  y: { min: -15, max: 15 },
  speed: 0.01,
  seed: 999
});

function updatePath() {
  const offsetX = pathAnimation.lastX;
  const offsetY = pathAnimation.lastY;
  
  // Update SVG path or transform
  svgElement.style.transform = `translate(${offsetX}px, ${offsetY}px)`;
  
  requestAnimationFrame(updatePath);
}
updatePath();

💡 Best Practices

✅ Do

• Use CSS for initial positioning: Position elements with CSS classes rather than inline styles
• Set proper positioning: Ensure elements have position: relative, absolute, or fixed
• Use percentage values for responsive designs: Great for mobile-friendly animations
• Choose appropriate speeds: Start with 0.01 and adjust based on desired effect
• Clean up animations: Call destroy() when removing elements from DOM

❌ Don't

• Don't rely on inline positioning: PerlinDOM works from any position, but CSS is cleaner
• Don't use on static elements: Transform won't work without proper positioning
• Don't forget to destroy: Memory leaks can occur if animations aren't cleaned up
• Don't use extreme speeds: Very high speeds can cause jittery animations

🎯 Performance Tips

// Good: Reuse animation instances
const sharedAnimation = new PerlinDOM({...});

// Good: Use percentage values for responsive design
x: { min: '-5%', max: '5%' }

// Good: Appropriate speeds for smooth animation
speed: 0.01  // Smooth and natural

// Good: Clean up when done
animation.destroy();

📖 API Reference

Constructor

new PerlinDOM(options)

Methods

| Method | Description | Returns | |--------|-------------|---------| | play() | Start or resume animation | void | | pause() | Smoothly pause animation | void | | destroy() | Stop animation and clean up resources | void | | init(seed?) | Reinitialize with optional new seed | void |

Properties

| Property | Type | Description | |----------|------|-------------| | lastX | number | Current X offset value | | lastY | number | Current Y offset value | | isPlaying | boolean | Current animation state | | speed | number | Animation speed (writable) | | lerpSpeed | number | Transition speed (writable) |

🔧 Troubleshooting

Common Issues

❓ Animation not visible

/* Ensure element has positioning */
.my-element {
  position: relative; /* or absolute/fixed */
}

❓ Element jumps on initialization

• PerlinDOM automatically detects current position
• If element has conflicting inline styles, consider moving to CSS

❓ Animation too fast/slow

// Adjust speed value
speed: 0.001  // Very slow
speed: 0.01   // Normal
speed: 0.1    // Fast

❓ Percentage values not working

• Ensure parent container has defined dimensions
• PerlinDOM calculates percentages based on parent size

❓ Memory leaks

// Always clean up when removing elements
animation.destroy();

Browser DevTools

Monitor performance in DevTools:

• Check for smooth 60fps in Performance tab
• Verify transform properties are being animated (not layout properties)

🌐 Browser Compatibility

PerlinDOM works in all modern browsers supporting:

• ✅ ES6 Modules (2015+)
• ✅ requestAnimationFrame (IE10+)
• ✅ CSS Transforms (IE9+)
• ✅ getComputedStyle (IE9+)

Tested Browsers

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

📝 Changelog

See CHANGELOG.md for detailed version history.

Recent Updates

• v0.0.6: Enhanced PerlinDOM to preserve design transforms
• v0.0.4: Package now public on npm, enhanced module exports configuration
• v0.0.3: Fixed positioning conflicts, improved automatic position detection
• v0.0.2: Added percentage support and responsive animations
• v0.0.1: Initial release with core Perlin noise animations

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by Andres Clua

PerlinDOM - Bringing organic motion to the web