Skip to main content

useSynchronizedAnimation: Multi-Component Animation Sync

Best Practices Guide for Shared CSS Animations

Introduction​

Ensuring that multiple elements across different components animate in perfect sync can be a challenge. The useSynchronizedAnimation hook leverages the Web Animations API to ensure that all animations with the same name stay aligned, regardless of when each element was added to the DOM.

How it works​

  1. Discovery: The hook uses document.getAnimations() to find all animations matching a specific animationName.
  2. Tracking: It maintains a global stashedTime for each animation name.
  3. Synchronization: When a new component mounts, its animation's currentTime is instantly synced to either the already-running instances or the last-known stashedTime.
  4. Resilience: It handles components mounting and unmounting at different times, ensuring the phase of the animation remains consistent for all visible elements.

Why use useSynchronizedAnimation?​

  • Visual Polish: Prevents "jarring" effects where identical animations (like spinners or pulsing backgrounds) are out of phase.
  • Declarative Interface: Just provide the animation name and a ref, and the hook handles the complex timing logic.
  • Low Overhead: Uses the browser's native animation engine rather than manually calculating styles in JavaScript.

See Also​

For a detailed technical breakdown and additional implementation patterns, refer to the following resources:

Key Takeaways​

  • Use descriptive animation names: Avoid generic names like fade or rotate. Instead, use specific names like global-pulse-effect to prevent accidental synchronization of unrelated UI elements.
  • Combine with CSS variables: Use the hook for timing synchronization while using CSS variables for style variations (e.g., different colors for the same synced pulse).
  • Check for browser support: While the hook handles support internally, be aware that the Web Animations API is required for synchronization to work.
  • Attach the ref correctly: The hook MUST be attached to the specific DOM element that carries the CSS animation name.