Creating Lifecycle Hooks (AnimX.hook)

Sometimes you want to add a feature to every single animation in your app automatically. For example, maybe you want every animation to automatically pause when scrolled out of view, or automatically delete itself from the DOM when finished.

Instead of writing this code manually on every single animate() call, you can create a Lifecycle Hook using AnimX.hook().

In this guide, we will build a wobbleHook step-by-step. Whenever an animation finishes, this hook will automatically add a playful "wobble" effect to the element, simply by passing a single custom flag.

---

Step 1: The Hook Function

A hook is just a regular JavaScript function. AnimX will call this function the exact moment a new animation is created (before it even starts playing).

const wobbleHook = (playable, config) => {
  // We will add our logic here
};

Let's look at the two arguments AnimX passes to our function:

• playable: This is the actual animation instance (like a Tween or Timeline). We can modify its properties (like .duration) or attach events (like .onComplete).
• config: This is the configuration object the user passed into animate(). For example, if they typed { duration: 1, wobble: true }, you can read config.wobble here.

---

Step 2: Checking Conditions

We don't want every single animation in our entire app to wobble. We only want it to happen if the developer explicitly asks for it by passing wobble: true and providing the HTML element (el).

const wobbleHook = (playable, config) => {
  // Check if the developer asked for the wobble effect, and provided the target element
  if (config.wobble && config.el) {
    // Proceed with our logic...
  }
};

---

Step 3: Safely Overriding Events

We want our wobble to happen exactly when the main animation finishes. To do this, we need to use the playable.onComplete event.

However, we must be careful! The user might have already defined their own onComplete event in their config. If we just overwrite it, we will break their code. Here is the safe way to wrap an event:

const wobbleHook = (playable, config) => {
  if (config.wobble && config.el) {
    
    // 1. Save the original function that the user might have written
    const originalComplete = playable.onComplete;
    
    // 2. Assign our new function
    playable.onComplete = () => {
      
      // (We will add the wobble animation here in the next step)
      
      // 3. Call the user's original function so we don't break their code!
      if (originalComplete) {
        originalComplete();
      }
    };
  }
};

---

Step 4: Spawning the Wobble

Inside our new onComplete function, we will use AnimX to spawn a quick, repeating rotation animation.

javascript
// ... inside the new onComplete:

animate(config.el, {
  rotation: 15,    // Rotate 15 degrees
  duration: 0.1,   // Very fast
  yoyo: true,      // Go back and forth
  repeat: 3,       // Do it 3 times
  ease: 'linear'
});

---

Step 5: Register and Use!

Finally, we tell AnimX to start using our hook globally via AnimX.hook().

import { animate, hook } from 'animx';

// Register the hook globally
hook(wobbleHook);

// Now, we can trigger the wobble with a single flag!
animate('.wobble-box', {
  x: 200,
  duration: 1,
  wobble: true, // The hook detects this!
  el: document.querySelector('.wobble-box')
});

Final Result

Here is the complete, working code in action. Notice how it cleanly slides to the right, and then the hook automatically triggers the wobble effect!

Click replay to execute

60 FPS