deveb-animation

v1.0.0

Published

7 months ago

A Three.js based scroll-triggered animation library with smooth scrolling

Downloads

0High
0Medium
0Low

savyasharma

three.js animation scroll gsap lenis webgl shader

Deveb Animation Library

A powerful Three.js based scroll-triggered animation library with smooth scrolling capabilities. Create stunning WebGL animations that respond to scroll events with ease.

Features

🎨 Beautiful Three.js WebGL animations
📜 Scroll-triggered animations using GSAP ScrollTrigger
🌊 Smooth scrolling with Lenis
🎭 Customizable shader materials
⚙️ Fully configurable options
📦 Zero dependencies (peer dependencies only)

Installation

npm install deveb-animation

Peer Dependencies

Make sure to install the required peer dependencies:

npm install three gsap lenis

Quick Start

Basic Usage

import { DevebAnimation } from 'deveb-animation';

// Initialize the animation
const animation = new DevebAnimation({
  canvas: document.querySelector('#my-canvas'),
  scrollTrigger: '.landing-section'
});

animation.init();

HTML Setup

<!DOCTYPE html>
<html>
<head>
  <title>My Animation</title>
</head>
<body>
  <div class="landing-section">
    <h1>My Heading</h1>
    <p>My paragraph text</p>
  </div>
  <canvas id="my-canvas"></canvas>
  
  <script type="module">
    import { DevebAnimation } from 'deveb-animation';
    
    const animation = new DevebAnimation({
      canvas: document.querySelector('#my-canvas'),
      scrollTrigger: '.landing-section'
    });
    
    animation.init();
  </script>
</body>
</html>

Configuration Options

const animation = new DevebAnimation({
  // Canvas element (required)
  canvas: document.querySelector('canvas'),
  
  // Scroll trigger selector
  scrollTrigger: '.landing',
  
  // ScrollTrigger start position
  scrollStart: 'top top',
  
  // ScrollTrigger end position
  scrollEnd: 'bottom center',
  
  // Scroll scrub duration
  scrollScrub: 2.3,
  
  // Lenis smooth scroll options
  lenisOptions: {
    autoRaf: true,
    lerp: 0.03
  },
  
  // Geometry configuration
  geometry: {
    type: 'icosahedron',
    radius: 1,
    detail: 200
  },
  
  // Initial mesh position
  initialPosition: {
    y: -1.4,
    z: 2
  },
  
  // Target mesh position (on scroll)
  targetPosition: {
    y: 0,
    z: -1
  },
  
  // Custom scroll callback
  onScroll: (e) => {
    console.log('Scroll event:', e);
  }
});

API Reference

Methods

`init()`

Initializes the animation. Must be called after creating an instance.

const animation = new DevebAnimation({ /* options */ });
animation.init();

`destroy()`

Cleans up all resources, removes event listeners, and stops the animation loop.

animation.destroy();

`getScene()`

Returns the Three.js Scene object for advanced customization.

const scene = animation.getScene();
scene.add(/* your custom objects */);

`getCamera()`

Returns the Three.js Camera object for advanced customization.

const camera = animation.getCamera();
camera.position.set(0, 0, 5);

`getRenderer()`

Returns the Three.js WebGLRenderer object for advanced customization.

const renderer = animation.getRenderer();
renderer.setClearColor(0x000000);

`getMesh()`

Returns the animated mesh object for advanced customization.

const mesh = animation.getMesh();
mesh.rotation.x += 0.01;

Advanced Usage

Customizing the Animation

const animation = new DevebAnimation({
  canvas: document.querySelector('canvas'),
  scrollTrigger: '.landing',
  initialPosition: { y: -2, z: 3 },
  targetPosition: { y: 1, z: -2 }
});

animation.init();

// Access Three.js objects for customization
const mesh = animation.getMesh();
const material = mesh.material;

// Modify shader uniforms
material.uniforms.uColorChange.value = 0.5;

// Add custom objects to the scene
const scene = animation.getScene();
const light = new THREE.DirectionalLight(0xffffff, 1);
scene.add(light);

Handling Scroll Events

const animation = new DevebAnimation({
  canvas: document.querySelector('canvas'),
  scrollTrigger: '.landing',
  onScroll: (e) => {
    // Custom scroll handling
    console.log('Scroll progress:', e.progress);
  }
});

animation.init();

Building

Build Library Only

npm run build:lib

This creates the library build in dist/lib/ with multiple formats:

deveb-animation.es.js - ES Module format
deveb-animation.umd.js - UMD format (for browsers)
deveb-animation.cjs.js - CommonJS format

Build App Only

npm run build:app

This builds your demo application in dist/app/.

Build Both

npm run build:all

Development

# Run development server
npm run dev

# Preview production build
npm run preview

Browser Support

Modern browsers with WebGL support
ES6+ JavaScript support required

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.