VZ Scroll Interactions

A lightweight, universal scroll interaction library that works with any framework - vanilla JavaScript, React, Vue, Angular, and more. Create smooth scroll-triggered animations with minimal setup.

Features

• 🚀 Universal: Works with any framework or vanilla JavaScript
• 🪶 Lightweight: Minimal footprint with no dependencies
• ⚡ Performance: Optimized scroll handling with built-in throttling
• 🎯 Precise: Advanced trigger point calculations
• 🧹 Clean: Automatic cleanup and memory management
• 📱 Responsive: Built-in viewport width tracking

Installation

npm install vz-scroll-interactions

Quick Start

Vanilla JavaScript

import scrollTrigger from 'vz-scroll-interactions';

const element = document.querySelector('.my-element');

scrollTrigger.createInstance('fade-in', element, {
  values: [[0, 1]], // Animate from 0 to 1
  startPoint: [0.8], // Start when element is 80% in viewport
  endPoint: [0.2], // End when element is 20% in viewport
  callback: ({ v }) => {
    element.style.opacity = v[0];
  }
});

React

import { useEffect, useRef } from 'react';
import scrollTrigger from 'vz-scroll-interactions';

function AnimatedComponent() {
  const elementRef = useRef();

  useEffect(() => {
    const instance = scrollTrigger.createInstance('slide-in', elementRef, {
      values: [[100, 0]], // Slide from 100px to 0px
      callback: ({ v }) => {
        elementRef.current.style.transform = `translateX(${v[0]}px)`;
      }
    });

    return () => {
      scrollTrigger.removeInstance('slide-in');
    };
  }, []);

  return <div ref={elementRef}>Animated content</div>;
}

Vue

import { ref, onMounted, onUnmounted } from 'vue';
import scrollTrigger from 'vz-scroll-interactions';

export default {
  setup() {
    const elementRef = ref();

    onMounted(() => {
      scrollTrigger.createInstance('rotate', elementRef, {
        values: [[0, 360]], // Rotate from 0 to 360 degrees
        callback: ({ v }) => {
          elementRef.value.style.transform = `rotate(${v[0]}deg)`;
        }
      });
    });

    onUnmounted(() => {
      scrollTrigger.removeInstance('rotate');
    });

    return { elementRef };
  }
};

API Reference

Main Methods

createInstance(key, element, options)

Creates a new scroll interaction instance.

Parameters:

• key (string): Unique identifier for the instance
• element (HTMLElement | Ref): Target element or React/Vue ref
• options (object): Configuration options

Options:

{
  values: [[startValue, endValue]], // Array of value pairs to animate
  startPoint: [0.5], // When animation starts (0-1, viewport percentage)
  endPoint: [0.5], // When animation ends
  callback: ({ v, ref, vw, start, end }) => {}, // Animation callback
  unrestrictedCallback: ({ ref, vw }) => {}, // Always-called callback
  isUnrestricted: false // Whether to use unrestricted mode
}

removeInstance(key)

Removes a scroll interaction instance and cleans up resources.

toggleInstance(key, enabled)

Enables or disables a specific instance without removing it.

Advanced Methods

calcTop(element, customStart)

calcBot(element, customEnd)

distance(element)

calcPercent(start, end, current)

calcCurrent(start, end, percentage)

Utility methods for custom calculations.

Global Configuration

setVzSIFactor(factor)

Sets a global scaling factor for all calculations (useful for responsive designs).

import { setVzSIFactor } from 'vz-scroll-interactions';

// Scale all calculations by 0.8
setVzSIFactor(0.8);

Advanced Usage

Multiple Value Animations

scrollTrigger.createInstance('complex-animation', element, {
  values: [
    [0, 100],    // First value: 0 to 100
    [1, 0],      // Second value: 1 to 0
    [0, 360]     // Third value: 0 to 360
  ],
  callback: ({ v }) => {
    element.style.transform = `translateX(${v[0]}px) scale(${v[1]}) rotate(${v[2]}deg)`;
  }
});

Custom Trigger Points

// Start when element top hits 80% of viewport
// End when element bottom hits 20% of viewport
scrollTrigger.createInstance('custom-trigger', element, {
  startPoint: [0.8],
  endPoint: [0.2],
  values: [[0, 1]],
  callback: ({ v, start, end }) => {
    console.log(`Progress: ${v[0]}, Start: ${start}, End: ${end}`);
  }
});

Responsive Animations

scrollTrigger.createInstance('responsive', element, {
  values: [[0, 100]],
  callback: ({ v, vw }) => {
    // Different animations based on viewport width
    if (vw <= 768) {
      element.style.transform = `translateY(${v[0]}px)`;
    } else {
      element.style.transform = `translateX(${v[0]}px)`;
    }
  }
});

Browser Support

• Modern browsers (ES6+)
• IE11+ (with polyfills)
• Mobile browsers
• Server-side rendering safe

Performance Tips

1. Reuse instances when possible instead of creating new ones
2. Use throttling for heavy animations
3. Clean up instances when components unmount
4. Batch DOM updates in your callbacks

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions