@andresclua/perlindom 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.3] - 2025-01-07
+
+### Fixed
+- **Positioning Issue**: Fixed problem where inline styles (`left`, `top`) were conflicting with transform animations, causing double positioning
+- **Transform Initialization**: PerlinDOM now properly initializes transform property if it doesn't exist
+
+### Improved
+- **Automatic Position Detection**: PerlinDOM now automatically detects and works from the element's current position (CSS or inline styles)
+- **Cleaner API**: No need for specific inline styles - elements animate from wherever they are positioned
+- **Better Performance**: Improved transform handling for smoother animations
+
+### Documentation
+- **README**: Completely restructured with better organization and clearer examples
+- **Examples**: Cleaned up HTML examples, moved positioning from inline styles to CSS classes
+- **Best Practices**: Added section explaining when to use CSS vs inline styles
+- **Troubleshooting**: New section with common issues and solutions
+
+### Code Quality
+- **Examples Cleanup**: Removed unnecessary inline styles from demo particles
+- **CSS Organization**: Better separation of positioning and styling concerns
+
+## [0.0.2] - 2024-12-XX
+
+### Added
+- **Percentage Support**: Added support for percentage-based movement values (`'-10%'`, `'10%'`)
+- **Responsive Animations**: Animations now adapt to container size changes
+- **Mixed Values**: Support for mixing pixel and percentage values in same animation
+- **Window Resize Handling**: Automatic recalculation when using percentage values
+
+### Features
+- **2D Perlin Noise**: Enhanced noise generation for more natural movement patterns
+- **Smooth Transitions**: Improved lerp-based pause/play functionality
+- **Performance Optimization**: Better requestAnimationFrame usage
+
+## [0.0.1] - 2024-11-XX
+
+### Added
+- **Initial Release**: Basic PerlinDOM functionality
+- **Core Animation**: Smooth organic animations using Perlin noise
+- **Basic API**: Constructor with element, x/y ranges, speed, and seed options
+- **Control Methods**: `play()`, `pause()`, `destroy()`, and `init()` methods
+- **Transform-based Movement**: CSS transform animations for better performance
+
+### Features
+- **Perlin Noise Generation**: Custom implementation with seeded random generation
+- **Configurable Ranges**: Separate X and Y movement ranges
+- **Speed Control**: Adjustable animation speed
+- **Seed Support**: Reproducible animations with custom seeds
+- **Element Positioning**: Automatic relative positioning for static elements
+
+---
+
+## Legend
+
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Vulnerability fixes
+- **Improved**: Performance or usability improvements
+- **Documentation**: Documentation changes
+- **Code Quality**: Code organization and cleanup

package/package.json

@@ -1,15 +1,15 @@
 {
     "name": "@andresclua/perlindom",
     "private": false,
-    "version": "0.0.2",
+    "version": "0.0.4",
     "description": "A lightweight JavaScript library for creating smooth, organic animations for DOM elements using Perlin noise",
     "type": "module",
-    "main": "./dist/perlindom.umd.js",
-    "module": "./dist/perlindom.es.js",
+    "main": "./dist/PerlinDOM.umd.js",
+    "module": "./dist/PerlinDOM.es.js",
     "exports": {
         ".": {
-            "import": "./dist/perlindom.es.js",
-            "require": "./dist/perlindom.umd.js"
+            "import": "./dist/PerlinDOM.es.js",
+            "require": "./dist/PerlinDOM.umd.js"
         }
     },
     "keywords": [

package/readme.md

@@ -1,319 +1,351 @@
 # PerlinDOM
 
-A lightweight JavaScript library for creating organic and fluid animations on DOM elements using Perlin noise.
-
-## Description
-
-PerlinDOM allows you to animate HTML elements with natural and organic movements based on Perlin noise. This technique creates movements that appear random but are smooth and predictable, perfect for subtle and attractive visual effects.
-
-## Methods
-
-| Method | Description |
-|--------|-------------|
-| `play()` | Starts or resumes the animation |
-| `pause()` | Pauses the animation |
-| `destroy()` | Stops the animation and cleans up resources |
-| `init(seed)` | Reinitializes the animation with an optional new seed |
-
-## Features
-
-- **Organic animations**: Natural movements that avoid the rigidity of traditional animations
-- **Customizable**: Control over movement ranges, speed, and noise seed
-- **Responsive**: Support for percentage-based values that adapt to container size
-- **Lightweight**: Minimal implementation with no external dependencies
-- **Easy to use**: Simple API to implement complex effects
-- **Optimized performance**: Uses requestAnimationFrame for smooth animations
-
-## Installation
+[![npm version](https://badge.fury.io/js/@andresclua%2Fperlindom.svg)](https://badge.fury.io/js/@andresclua%2Fperlindom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![JavaScript](https://img.shields.io/badge/JavaScript-ES6+-yellow.svg)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+
+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](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Configuration](#-configuration)
+- [Examples](#-examples)
+- [Best Practices](#-best-practices)
+- [API Reference](#-api-reference)
+- [Troubleshooting](#-troubleshooting)
+- [Browser Compatibility](#-browser-compatibility)
+- [Changelog](#-changelog)
+- [License](#-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
 
 ```bash
-npm install @andresclua/PerlinDOM
+npm install @andresclua/perlindom
 ```
 
+Or include directly in your HTML:
+
+```html
+<script type="module">
+  import PerlinDOM from 'https://unpkg.com/@andresclua/perlindom/dist/perlindom.es.js';
+</script>
+```
 
-## Basic Usage
+## 🚀 Quick Start
 
 ```javascript
-import PerlinDOM from '@andresclua/PerlinDOM';
+import PerlinDOM from '@andresclua/perlindom';
 
-// Create a basic animation
+// Basic animation - element will animate from its current position
 const animation = new PerlinDOM({
   element: document.querySelector('.my-element'),
-  x: { min: -50, max: 50 },  // Horizontal movement range in pixels
-  y: { min: -50, max: 50 },  // Vertical movement range in pixels
+  x: { min: -50, max: 50 },  // Move ±50px horizontally
+  y: { min: -30, max: 30 },  // Move ±30px vertically
   speed: 0.01,               // Animation speed
-  seed: 123                  // Seed for the noise generator
+  seed: 123                  // Reproducible pattern
 });
+
+// Control the animation
+animation.pause();  // Smooth pause
+animation.play();   // Resume
+animation.destroy(); // Clean up
 ```
 
-## Configuration Options
+```css
+/* 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 */
+}
+```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `element` | HTMLElement | The DOM element to animate |
-| `x` | Object or null | Horizontal movement configuration: `{min: value, max: value}`. Values can be numbers (pixels) or strings with '%' (percentage of parent width). Use `null` to disable horizontal movement |
-| `y` | Object or null | Vertical movement configuration: `{min: value, max: value}`. Values can be numbers (pixels) or strings with '%' (percentage of parent height). Use `null` to disable vertical movement |
-| `speed` | Number | Animation speed (smaller values = slower movement) |
-| `seed` | Number | Seed for the Perlin noise generator |
-| `lerpSpeed` | Number | Interpolation speed for smooth transitions (default: 0.1) |
+## ⚙️ Configuration
 
-> **⚠️ Important**: For PerlinDOM to work correctly, the animated element **must** have a CSS `position` property set to `absolute`, `relative`, or `fixed`. Without this property, the animation will not function as expected.
+| 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 |
 
-## Percentage-Based Values
+### Value Types
 
-PerlinDOM now supports percentage-based values for movement ranges, allowing for responsive animations that adapt to the size of the parent container:
+- **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`
 
-```javascript
-const responsiveAnimation = new PerlinDOM({
-  element: document.querySelector('.responsive-element'),
-  x: { min: '-10%', max: '10%' },  // 10% of parent width in each direction
-  y: { min: '-5%', max: '5%' },    // 5% of parent height in each direction
-  speed: 0.01,
-  seed: 123
-});
-```
+## 📚 Examples
 
-You can also mix pixel and percentage values:
+### 1. Basic Element Animation
 
-```javascript
-const mixedAnimation = new PerlinDOM({
-  element: document.querySelector('.mixed-element'),
-  x: { min: '-10%', max: '10%' },  // Percentage-based horizontal movement
-  y: { min: -20, max: 20 },        // Pixel-based vertical movement
-  speed: 0.01,
-  seed: 456
-});
+```html
+<div class="floating-card">Content</div>
 ```
 
-When using percentage values, PerlinDOM automatically recalculates the movement range when the window is resized, ensuring that your animations remain proportional to their container.
-
-## Examples
-
-### 1. Basic Animation
-
-Create an element with smooth movement on both axes.
+```css
+.floating-card {
+  position: relative;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+}
+```
 
 ```javascript
-const basicAnimation = new PerlinDOM({
-  element: document.querySelector('.element'),
-  x: { min: -50, max: 50 },
-  y: { min: -50, max: 50 },
-  speed: 0.01,
-  seed: 123
+new PerlinDOM({
+  element: document.querySelector('.floating-card'),
+  x: { min: -20, max: 20 },
+  y: { min: -15, max: 15 },
+  speed: 0.008,
+  seed: 42
 });
 ```
 
-### 2. Horizontal-Only Movement
-
-Animate an element only on the horizontal axis.
+### 2. Responsive Background Elements
 
 ```javascript
-const horizontalAnimation = new PerlinDOM({
-  element: document.querySelector('.horizontal-element'),
-  x: { min: -100, max: 100 },
-  y: null, // No vertical movement
-  speed: 0.02
+// 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. Multiple Elements with Different Seeds
-
-Animate multiple elements with different patterns.
+### 3. Interactive Hover Effects
 
 ```javascript
-document.querySelectorAll('.particle').forEach((el, index) => {
-  new PerlinDOM({
-    element: el,
-    x: { min: -100, max: 100 },
-    y: { min: -100, max: 100 },
-    speed: 0.01,
-    seed: index * 100 // Different seed for each element
+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
   });
 });
-```
 
-### 4. Background Effect
+button.addEventListener('mouseleave', () => {
+  animation?.pause();
+});
+```
 
-Create a dynamic background with slowly moving elements.
+### 4. Multiple Elements with Synchronized Patterns
 
 ```javascript
-document.querySelectorAll('.bg-element').forEach(el => {
+// Same seed = synchronized movement
+document.querySelectorAll('.sync-element').forEach(el => {
   new PerlinDOM({
     element: el,
-    x: { min: -10, max: 10 },
-    y: { min: -10, max: 10 },
-    speed: 0.002, // Very slow movement
-    seed: Math.random() * 2000
+    x: { min: -30, max: 30 },
+    y: { min: -30, max: 30 },
+    speed: 0.01,
+    seed: 12345  // Same seed for all elements
   });
 });
 ```
 
-### 5. Pause and Play with Mouse Events
-
-Control the animation with mouse events.
+### 5. Custom Animation Patterns
 
 ```javascript
-const pausePlayAnimation = new PerlinDOM({
-  element: document.querySelector('.pause-element'),
-  x: { min: -80, max: 80 },
-  y: { min: -80, max: 80 },
-  speed: 0.01,
-  seed: 42,
-  lerpSpeed: 0.05 // Controls how smooth the transition is
-});
-
-// Pause on mouse leave
-document.querySelector('.container').addEventListener('mouseleave', () => {
-  pausePlayAnimation.pause();
+// 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
 });
 
-// Play on mouse enter
-document.querySelector('.container').addEventListener('mouseenter', () => {
-  pausePlayAnimation.play();
+// 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. Interactive Controls
-
-Allow the user to adjust animation parameters.
+### 6. Advanced: SVG Path Animation
 
 ```javascript
-// Create the animation with initial settings
-const interactiveAnimation = new PerlinDOM({
-  element: document.querySelector('.interactive-element'),
-  x: { min: -50, max: 50 },
-  y: { min: -50, max: 50 },
+// 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: 0
+  seed: 999
 });
 
-// Update settings based on user input
-speedControl.addEventListener('input', () => {
-  interactiveAnimation.speed = parseFloat(speedControl.value);
-  interactiveAnimation.init(); // Restart with new settings
-});
+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();
 ```
 
-### 7. Animated Button with Circles
+## 💡 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
 
-Create a button with animated hover effects.
+- **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
 
 ```javascript
-// Get all the circle elements inside the button
-const circleElements = document.querySelectorAll('.animated-button .circle');
-let circleAnimations = [];
-
-// Function to initialize animations
-function initCircleAnimations() {
-  // Clear existing animations
-  circleAnimations.forEach(anim => anim.destroy());
-  circleAnimations = [];
-  
-  // Create new animations for each circle
-  circleElements.forEach((el, index) => {
-    const animation = new PerlinDOM({
-      element: el,
-      x: { min: -15, max: 15 },
-      y: { min: -15, max: 15 },
-      speed: 0.03,
-      seed: index * 1000,
-      lerpSpeed: 0.1
-    });
-    circleAnimations.push(animation);
-  });
-}
+// Good: Reuse animation instances
+const sharedAnimation = new PerlinDOM({...});
 
-// Add event listeners to the button
-document.querySelector('.animated-button').addEventListener('mouseenter', () => {
-  initCircleAnimations();
-  circleAnimations.forEach(anim => anim.play());
-});
+// Good: Use percentage values for responsive design
+x: { min: '-5%', max: '5%' }
 
-document.querySelector('.animated-button').addEventListener('mouseleave', () => {
-  circleAnimations.forEach(anim => anim.pause());
-});
+// Good: Appropriate speeds for smooth animation
+speed: 0.01  // Smooth and natural
+
+// Good: Clean up when done
+animation.destroy();
 ```
 
-### 8. Triangle with Animated Vertex
+## 📖 API Reference
 
-Use PerlinDOM to animate a vertex of an SVG polygon.
+### Constructor
 
 ```javascript
-// Get the polygon element
-const trianglePath = document.getElementById('trianglePath');
-
-// Store the original points
-const originalPoints = {
-  x1: 150, y1: 50,  // Top vertex
-  x2: 250, y2: 250, // Bottom right
-  x3: 50,  y3: 250  // Bottom left
-};
-
-// Create a custom animation function
-function animateTriangle() {
-  // Create a PerlinDOM instance for the top vertex
-  const topVertexAnimation = new PerlinDOM({
-    element: null, // We're not moving a DOM element directly
-    x: { min: -30, max: 30 },
-    y: { min: -20, max: 20 },
-    speed: 0.005,
-    seed: 42
-  });
+new PerlinDOM(options)
+```
 
-  // Animation function
-  function updateTriangle() {
-    // Get the current noise values
-    const offsetX = topVertexAnimation.lastX;
-    const offsetY = topVertexAnimation.lastY;
+### Methods
 
-    // Update the polygon points
-    const newPoints = `${originalPoints.x1 + offsetX},${originalPoints.y1 + offsetY} ${originalPoints.x2},${originalPoints.y2} ${originalPoints.x3},${originalPoints.y3}`;
-    trianglePath.setAttribute('points', newPoints);
+| 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` |
 
-    // Continue animation
-    requestAnimationFrame(updateTriangle);
-  }
+### Properties
 
-  // Start the animation
-  updateTriangle();
-}
+| 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) |
 
-// Initialize the animation
-animateTriangle();
-```
+## 🔧 Troubleshooting
+
+### Common Issues
 
-### 9. Responsive Animation with Percentage Values
+**❓ Animation not visible**
+```css
+/* Ensure element has positioning */
+.my-element {
+  position: relative; /* or absolute/fixed */
+}
+```
 
-Create an animation that adapts to the size of its container.
+**❓ Element jumps on initialization**
+- PerlinDOM automatically detects current position
+- If element has conflicting inline styles, consider moving to CSS
 
+**❓ Animation too fast/slow**
 ```javascript
-const responsiveAnimation = new PerlinDOM({
-  element: document.querySelector('.responsive-element'),
-  x: { min: '-15%', max: '15%' },  // 15% of parent width in each direction
-  y: { min: '-10%', max: '10%' },  // 10% of parent height in each direction
-  speed: 0.008,
-  seed: 789
-});
+// Adjust speed value
+speed: 0.001  // Very slow
+speed: 0.01   // Normal
+speed: 0.1    // Fast
+```
 
-// The animation will automatically adjust when the window is resized
-// No additional code needed for responsiveness
+**❓ Percentage values not working**
+- Ensure parent container has defined dimensions
+- PerlinDOM calculates percentages based on parent size
+
+**❓ Memory leaks**
+```javascript
+// Always clean up when removing elements
+animation.destroy();
 ```
 
-## Use Cases
+### 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](./CHANGELOG.md) for detailed version history.
+
+### Recent Updates
+
+- **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
 
-- **Background elements**: Create dynamic and organic backgrounds
-- **Hover effects**: Enhance the interactivity of buttons and links
-- **Data visualizations**: Add subtle movement to charts and visualizations
-- **Decorative elements**: Bring decorative elements to life on your website
-- **User interfaces**: Create more dynamic and attractive interfaces
+## 📄 License
 
-## Compatibility
+MIT License - see [LICENSE](./LICENSE) file for details.
 
-PerlinDOM works in all modern browsers that support:
-- ES6 (ECMAScript 2015)
-- requestAnimationFrame
-- CSS positioning (absolute, relative, fixed)
+---
 
-## License
+**Made with ❤️ by [Andres Clua](https://github.com/andresclua)**
 
-MIT
+*PerlinDOM - Bringing organic motion to the web*

package/src/index.html

@@ -59,8 +59,8 @@
               background-color: #3498db;
               border-radius: 50%;
               position: absolute;
-              left: calc(50% - 40px); /* 50% - half width */
-              top: calc(50% - 40px); /* 50% - half height */
+              left: calc(50% - 40px);
+              top: calc(50% - 40px);
               filter: blur(5px);
             }
             
@@ -86,6 +86,32 @@
               filter: blur(10px);
             }
             
+            /* Positioning for particles - these are initial positions, PerlinDOM will animate from here */
+            .particle:nth-child(1) {
+              left: 30%;
+              top: 30%;
+            }
+            
+            .particle:nth-child(2) {
+              left: 50%;
+              top: 50%;
+            }
+            
+            .particle:nth-child(3) {
+              left: 70%;
+              top: 70%;
+            }
+            
+            .particle:nth-child(4) {
+              left: 30%;
+              top: 70%;
+            }
+            
+            .particle:nth-child(5) {
+              left: 70%;
+              top: 30%;
+            }
+            
             /* Example 4: Background Effect */
             .bg-container {
               background-color: #34495e;
@@ -403,11 +429,11 @@
           });
         </div>
         <div class="example-container">
-          <div class="particle" style="left: 30%; top: 30%"></div>
-          <div class="particle" style="left: 50%; top: 50%"></div>
-          <div class="particle" style="left: 70%; top: 70%"></div>
-          <div class="particle" style="left: 30%; top: 70%"></div>
-          <div class="particle" style="left: 70%; top: 30%"></div>
+          <div class="particle"></div>
+          <div class="particle"></div>
+          <div class="particle"></div>
+          <div class="particle"></div>
+          <div class="particle"></div>
         </div>
         
         <!-- Example 4: Background Effect -->

package/src/js/PerlinDom.js

@@ -60,17 +60,24 @@ class PerlinDOM {
   
       // Solo inicializar estas propiedades si el elemento no es null
       if (element) {
-        this.initialX = element.offsetLeft;
-        this.initialY = element.offsetTop;
+        // Ensure element has positioning for transform to work properly
+        const computedStyle = window.getComputedStyle(element);
+        if (computedStyle.position === 'static') {
+          element.style.position = 'relative';
+        }
+        
+        // Initialize transform if it doesn't exist
+        const currentTransform = computedStyle.transform;
+        if (!currentTransform || currentTransform === 'none') {
+          element.style.transform = 'translate3d(0px, 0px, 0px)';
+        }
         
         // If using percentages, add resize listener
         if (this.hasPercentages) {
           this.handleResize = this.handleResize.bind(this);
           window.addEventListener('resize', this.handleResize);
         }
-      } else {
-        this.initialX = 0;
-        this.initialY = 0;
+  
       }
       
       this.animate = this.animate.bind(this);
@@ -263,9 +270,8 @@ class PerlinDOM {
           this.lastX = valX;
           this.lastY = valY;
       
-          // Update position using left/top
-          this.el.style.left = `${this.initialX + valX}px`;
-          this.el.style.top = `${this.initialY + valY}px`;
+          // Update position using transform for better performance
+          this.el.style.transform = `translate3d(${valX}px, ${valY}px, 0)`;
         } else {
           // If no element, just calculate and store the values
           const valX = this.xRange