@hngbfv3399/scrollschot-core v2.0.0

@scrollschot/core

Lightweight, performance-optimized scroll animation library with TypeScript support

⚡ Quick Start

npm install @scrollschot/core

import { ScrollSchot } from '@scrollschot/core';

// Initialize
const scrollSchot = new ScrollSchot();

// Add scroll animation
scrollSchot.addTrigger({
  element: document.querySelector('.my-element'),
  animation: {
    name: 'fadeInUp',
    duration: 1000,
    easing: 'ease-out'
  }
});

🚀 Features

• 🪶 Lightweight: Only 15KB gzipped
• ⚡ Fast: Uses Intersection Observer API for optimal performance
• 📱 Mobile-first: Works seamlessly across all devices
• 🎯 Zero dependencies: No external dependencies
• 📝 TypeScript: Full type support and IntelliSense
• 🎨 20+ Animations: Rich collection of built-in animations
• ⚙️ Configurable: Extensive customization options

📋 Built-in Animations

Fade Animations

• fadeIn / fadeOut
• fadeInUp / fadeInDown
• fadeInLeft / fadeInRight

Slide Animations

• slideInLeft / slideOutLeft
• slideInRight / slideOutRight
• slideInUp / slideOutUp
• slideInDown / slideOutDown

Scale/Zoom Animations

• zoomIn / zoomOut
• scaleIn / scaleOut

Rotation Animations

• rotateIn / rotateOut
• flip / rollIn

Bounce Animations

• bounceIn / bounceOut

Special Effects

• pulse / shake / heartBeat

📚 Usage Examples

Basic Usage

import { ScrollSchot } from '@scrollschot/core';

const scrollSchot = new ScrollSchot({
  threshold: 0.1,
  rootMargin: '0px',
  debug: false
});

// Simple fade in animation
scrollSchot.addTrigger({
  element: document.querySelector('.hero'),
  animation: {
    name: 'fadeIn',
    duration: 1000
  }
});

Advanced Configuration

scrollSchot.addTrigger({
  element: document.querySelector('.card'),
  animation: {
    name: 'slideInLeft',
    duration: 800,
    delay: 200,
    easing: 'cubic-bezier(0.25, 0.46, 0.45, 0.94)',
    iterations: 1,
    fill: 'both'
  },
  threshold: 0.2,
  once: true,
  onStart: (element) => {
    console.log('Animation started!', element);
  },
  onEnd: (element) => {
    console.log('Animation completed!', element);
  }
});

Multiple Elements

const cards = document.querySelectorAll('.card');
const triggers = Array.from(cards).map((card, index) => ({
  element: card,
  animation: {
    name: 'fadeInUp',
    duration: 600,
    delay: index * 100 // Stagger effect
  }
}));

scrollSchot.addTriggers(triggers);

HTML Data Attributes

<div class="card" 
     data-ss-animation="fadeInLeft"
     data-ss-duration="800"
     data-ss-delay="200">
  Content here
</div>

// Auto-initialize from data attributes
const elements = document.querySelectorAll('[data-ss-animation]');
elements.forEach(element => {
  scrollSchot.addTrigger({
    element,
    animation: {
      name: element.dataset.ssAnimation,
      duration: parseInt(element.dataset.ssDuration) || 1000,
      delay: parseInt(element.dataset.ssDelay) || 0
    }
  });
});

CDN Usage

<script src="https://unpkg.com/@scrollschot/core@latest/dist/index.js"></script>
<script>
  const scrollSchot = new ScrollSchot.ScrollSchot();
  // ... use as above
</script>

🎨 Custom Animations

import { ScrollSchot } from '@scrollschot/core';

scrollSchot.addTrigger({
  element: document.querySelector('.custom'),
  animation: {
    name: 'fadeIn', // Base animation
    duration: 1000,
    customProperties: {
      transform: 'translateY(50px) scale(0.9)',
      opacity: '0'
    }
  }
});

⚙️ API Reference

ScrollSchot Constructor

new ScrollSchot(options?: ScrollSchotOptions)

Options:

• threshold?: number - Intersection threshold (default: 0.1)
• rootMargin?: string - Root margin for intersection observer (default: '0px')
• debug?: boolean - Enable debug logging (default: false)
• optimize?: boolean - Enable performance optimizations (default: true)

Methods

addTrigger(trigger: ScrollTrigger): void

Add a scroll animation trigger

addTriggers(triggers: ScrollTrigger[]): void

Add multiple triggers at once

removeTrigger(element: Element): void

Remove trigger for specific element

refresh(): void

Refresh all triggers (useful after DOM changes)

destroy(): void

Clean up and destroy the instance

getMetrics(): object

Get performance metrics

Animation Configuration

interface AnimationConfig {
  name: string;           // Animation name
  duration?: number;      // Duration in ms (default: 1000)
  delay?: number;         // Delay in ms (default: 0)
  easing?: string;        // CSS easing function (default: 'ease-out')
  direction?: string;     // Animation direction (default: 'normal')
  iterations?: number | 'infinite';  // Iterations (default: 1)
  fill?: string;          // Fill mode (default: 'both')
  customProperties?: Record<string, string>; // Custom CSS properties
}

🎯 Performance Tips

1. Use once: true for animations that should only run once
2. Optimize thresholds - Use higher values for better performance
3. Debounce DOM changes when adding/removing triggers frequently
4. Use optimize: true option for automatic performance optimizations
5. Destroy instances when no longer needed

🌟 Browser Support

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

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📞 Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions