Mastering Angular’s Animation event API with Third-Party Libraries

Mastering Angular Animate event API with Third-Party Libraries

Hey Devs

Building on our previous discussion of the new Animation API in Angular, let’s dive into a powerful use case: integrating this API with popular third-party animation libraries. This new feature provides a seamless bridge between Angular’s component lifecycle and the vast capabilities of external animation tools.

👉 Not a Medium member? You can read the full article for free by clicking here 🔗

How to Integrate Third-Party Libraries with Angular’s Animation API

The new API introduces simple and intuitive event bindings like (animate.enter) and (animate.leave). Let's break down how this works.

Consider the following HTML snippet:

HTML

<div class="header-section">
  <h1 class="title" (animate.enter)="titleAnimation($event)">
    ✨ Stylish Text Animation
  </h1>
  <p class="subtitle">Add and remove text with smooth animations</p>
</div>

The binding (animate.enter)="titleAnimation($event)" is the key. When this <h1> element is rendered and inserted into the DOM, the animate.enter event is triggered, calling our titleAnimation method.

In our component’s TypeScript file, the titleAnimation method receives a special event object:

TypeScript

titleAnimation(event: AnimationCallbackEvent) {
  // Logic to drive the animation goes here.
  // For example, using a library like GSAP or simply adding a CSS class.
}

This method receives a parameter of type AnimationCallbackEvent. This object is crucial for controlling the animation and has two key properties:

• target: This is the HTMLElement that triggered the animation, giving you a direct reference to the DOM element you need to animate.
• animationComplete: This is a callback function that you must call to signal to Angular that your animation has finished.

Important Note on animationComplete() It is essential to call the animationComplete() function, especially when using (animate.leave). This function notifies Angular that it’s safe to remove the element from the DOM.

If you don’t call animationComplete() for a leave animation, Angular will automatically call it for you after a default four-second delay to prevent the element from lingering indefinitely.

You can override this timeout by providing the MAX_ANIMATION_TIMEOUT token in your component’s providers

providers: [
  { provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 } // Sets a 6-second timeout
]

Full Component Example

Here is a complete example demonstrating two approaches: one using custom CSS classes and another showing how you would integrate a library like GSAP.

TypeScript

@Component({
  selector: "app-animation",
  imports: [FormsModule],
  template: `
    <div class="animation-container">
      <div class="header-section">
        <h1
          class="title"
          (animate.enter)="titleAnimationCustomCss($event)"
        >
          ✨ Stylish Text Animation
        </h1>
        <p class="subtitle">Add and remove text with smooth animations</p>
      </div>
    </div>
  `,
  styles: ` 
    /* Enhanced Animations */
    .fadein {
      animation: fadeInAnimation 2s ease-out forwards;
    }
.fadeout {
      animation: fadeOutAnimation 0.4s ease-in forwards;
    }
    .slideFadeIn {
      animation: slideFadeInAnimation 1s ease-out forwards;
    }
    .slideFadeOut {
      animation: slideFadeOutAnimation 1s ease-in forwards;
    }
    @keyframes fadeInAnimation {
      from {
        opacity: 0;
        transform: translateY(-10px);
      }
      to {
        opacity: 1;
        transform: translateY(0);
      }
    }
    @keyframes fadeOutAnimation {
      from {
        opacity: 1;
        transform: translateY(0);
      }
      to {
        opacity: 0;
        transform: translateY(-10px);
      }
    }
    @keyframes slideFadeInAnimation {
      from {
        opacity: 0;
        transform: translateX(-20px) scale(0.9);
      }
      to {
        opacity: 1;
        transform: translateX(0) scale(1);
      }
    }
    @keyframes slideFadeOutAnimation {
      from {
        opacity: 1;
        transform: translateX(0) scale(1);
      }
      to {
        opacity: 0;
        transform: translateX(20px) scale(0.9);
      }
    }
  `,
})
export class Animation {
  // Example of integrating a third-party library like GSAP
  titleAnimation(event: AnimationCallbackEvent) {
    // gsap.to(event.target, {
    //   duration: 1,
    //   x: 100,
    //   // Use the library's onComplete callback to notify Angular
    //   onComplete: () => event.animationComplete()
    // });
  }
  // Example of handling animations with custom CSS
  titleAnimationCustomCss(event: AnimationCallbackEvent) {
    event.target.classList.add('fadein');
    // You can call animationComplete immediately for CSS animations,
    // or use an 'animationend' event listener for more precise control.
    event.animationComplete();
  }
}

In the example above:

• The titleAnimationCustomCss method shows the simplest approach: adding a CSS class to the target element. The browser's rendering engine handles the animation based on your stylesheet.
• The commented-out titleAnimation method demonstrates how you would use a library like GSAP. You initiate the animation on event.target and then place event.animationComplete() inside the library's own completion callback (e.g., onComplete). This ensures Angular's lifecycle is perfectly synchronized with your external animation.

Conclusion

Angular’s latest Animation API is a powerful feature that provides incredible flexibility. By giving developers direct access to the animating element and a completion callback, it seamlessly bridges the gap between the Angular framework and the rich ecosystems of third-party animation libraries and custom CSS solutions.

🙌 Let’s Discuss Have you tried the Animate API in your apps yet? Thanks for reading! If this was helpful, consider clapping 👏 and following for more Angular tips. Got questions or suggestions? Drop them in the comments below!

✍️ Author: Vetriselvan Panneerselvam

👨‍💻 Frontend Developer | 💡 Code Enthusiast | 📚 Lifelong Learner | ✍️ Tech Blogger | 🌍 Freelance Developer