🎬 Animation Trigger

A simple, lightweight JavaScript library to animate multiple elements with custom animations on a single click. Zero dependencies, works with any framework (React, Vue, Vanilla JS).

✨ Features

• 🚀 Simple API - Just 3 lines of code!
• 🎯 Custom animations per element - Each element can have its own animation
• ⏱️ Delay & duration control - Set different start delays and durations for each animation
• 🎨 15+ built-in animations - Exit animations (slide, fade, zoom, rotate) + Enter animations (slide, fade, zoom, rotate, bounce)
• 🔄 Sequential execution - Animations run one after another automatically
• 🎛️ Initial visibility control - Set initial visibility for each element independently
• ⚡ Zero dependencies - Lightweight and fast
• 🔧 Works everywhere - React, Vue, Angular, or vanilla JS
• 📦 Tree-shakable - Only import what you need

📦 Installation

npm install animation-trigger

🚀 Quick Start

Vanilla JavaScript

import { AnimationTrigger } from 'animation-trigger';

new AnimationTrigger({
  items: [
    {
      element: '.modal',
      animation: 'slideOutUp',     // Exit animation
      startDelay: 0,               // Start immediately
      duration: 500,              // 500ms duration
      initialVisible: true        // Initially visible
    },
    {
      element: '.success-card',
      animation: 'slideInDown',    // Enter animation
      startDelay: 500,             // Start after 500ms
      duration: 600,              // 600ms duration
      initialVisible: false       // Initially hidden
    }
  ],
  activator: '#submitBtn',
  onComplete: () => {
    console.log('All animations finished!');
  }
});

React

import React, { useEffect } from 'react';
import { AnimationTrigger } from 'animation-trigger';

function App() {
  useEffect(() => {
    new AnimationTrigger({
      items: [
        { 
          element: '.form-card', 
          animation: 'slideOutLeft', 
          startDelay: 0, 
          duration: 500,
          initialVisible: true 
        },
        { 
          element: '.info-card', 
          animation: 'slideInRight', 
          startDelay: 500, 
          duration: 600,
          initialVisible: false 
        }
      ],
      activator: '#nextBtn'
    });
  }, []);

  return (
    <div>
      <div className="form-card">Form Content</div>
      <div className="info-card">Info Content</div>
      <button id="nextBtn">Next</button>
    </div>
  );
}

📖 API

AnimationTrigger(config)

| Parameter | Type | Description | |-----------|------|-------------| | items | AnimationItem[] | Array of animations to execute sequentially | | activator | string | CSS selector of the button that triggers animations | | onComplete | () => void | Optional callback after all animations finish |

AnimationItem

| Property | Type | Default | Description | |----------|------|---------|-------------| | element | string | required | CSS selector of the element to animate | | animation | string | required | Animation type (see list below) | | startDelay | number | 0 | Delay before animation starts (milliseconds) | | duration | number | 500 | Animation duration (milliseconds) | | initialVisible | boolean | auto | Initial visibility. If not set: true for exit animations, false for enter animations |

initialVisible Behavior

| initialVisible | Animation Type | Result | |------------------|----------------|--------| | true | Any | Element starts visible | | false | Any | Element starts hidden | | Not set | out (exit) | Element starts visible (auto) | | Not set | in (enter) | Element starts hidden (auto) |

🎨 Available Animations

Exit Animations (elements leave the screen)

| Animation | Description | |-----------|-------------| | slideOutLeft | Slides element out to the left | | slideOutRight | Slides element out to the right | | slideOutUp | Slides element out to the top | | slideOutDown | Slides element out to the bottom | | fadeOut | Fades element out | | zoomOut | Zooms out and fades element | | rotateOut | Rotates and fades element |

Enter Animations (elements appear on screen)

| Animation | Description | |-----------|-------------| | slideInLeft | Slides element in from the left | | slideInRight | Slides element in from the right | | slideInUp | Slides element in from the bottom | | slideInDown | Slides element in from the top | | fadeIn | Fades element in | | zoomIn | Zooms in and fades element | | rotateIn | Rotates and fades in | | bounceIn | Bounces in with elastic effect |

💡 Examples Example 1: Sequential animations with delays

new AnimationTrigger({
  items: [
    { element: '.header', animation: 'slideOutUp', startDelay: 0, duration: 500, initialVisible: true },
    { element: '.content', animation: 'fadeOut', startDelay: 300, duration: 400, initialVisible: true },
    { element: '.footer', animation: 'slideOutDown', startDelay: 600, duration: 500, initialVisible: true }
  ],
  activator: '#closeAll'
});

Example 2: Toggle between two elements

new AnimationTrigger({
  items: [
    { element: '.old-panel', animation: 'slideOutLeft', startDelay: 0, duration: 500, initialVisible: true },
    { element: '.new-panel', animation: 'slideInRight', startDelay: 500, duration: 600, initialVisible: false }
  ],
  activator: '#switchBtn'
});

Example 3: Modal with fade animation

new AnimationTrigger({
  items: [
    { element: '.modal', animation: 'zoomOut', startDelay: 0, duration: 300, initialVisible: true },
    { element: '.overlay', animation: 'fadeOut', startDelay: 0, duration: 300, initialVisible: true }
  ],
  activator: '#closeModal',
  onComplete: () => console.log('Modal closed!')
});

Example 4: Form submission with delayed success message

new AnimationTrigger({
  items: [
    { element: '.form', animation: 'slideOutUp', startDelay: 0, duration: 500, initialVisible: true },
    { element: '.loading', animation: 'fadeOut', startDelay: 500, duration: 300, initialVisible: true },
    { element: '.success-message', animation: 'bounceIn', startDelay: 800, duration: 600, initialVisible: false }
  ],
  activator: '#submitBtn',
  onComplete: () => console.log('Form submitted!')
});

Example 5: Multiple cards with different initial states

new AnimationTrigger({
  items: [
    { element: '.card-1', animation: 'slideOutLeft', startDelay: 0, duration: 400, initialVisible: true },
    { element: '.card-2', animation: 'slideOutLeft', startDelay: 200, duration: 400, initialVisible: true },
    { element: '.card-3', animation: 'slideOutLeft', startDelay: 400, duration: 400, initialVisible: true },
    { element: '.new-card', animation: 'slideInRight', startDelay: 800, duration: 500, initialVisible: false }
  ],
  activator: '#loadMore'
});

🔧 Advanced Usage Using AnimationEngine directly for more control

import { AnimationEngine } from 'animation-trigger';

// Initialize (adds styles to document)
AnimationEngine.init();

// Exit animation
const element = document.querySelector('.my-element');
AnimationEngine.exit(element, 'slideOutLeft', {
  duration: 800,
  removeAfter: true,
  onComplete: () => console.log('Animation done!')
});

// Enter animation
AnimationEngine.enter(element, 'bounceIn', {
  duration: 600,
  onComplete: () => console.log('Element appeared!')
});

Custom element visibility before animation The library automatically handles element visibility based on the initialVisible property:

Set initialVisible: true → element starts visible, will animate out if exit animation

Set initialVisible: false → element starts hidden, will animate in if enter animation

No need to manually set display: none or display: block in your CSS!

🛠️ Browser Support Works in all modern browsers that support CSS animations:

Chrome 45+

Firefox 42+

Safari 10+

Edge 15+

📝 License MIT © Hamidreza Norouzi

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

Fork the repository

Create your feature branch (git checkout -b feature/amazing)

Commit your changes (git commit -m 'Add some amazing feature')

Push to the branch (git push origin feature/amazing)

Open a Pull Request

📧 Contact GitHub: @hnorouzi

Email: [email protected]

Made with ❤️ by Hamidreza Norouzi