@andresclua/perlindom

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