Animate with Mercury

Animations are not directly handled by Mercury itself, nowadays there is enough good animation libraries for JS that there is no need to reinvent the wheel. Instead Mercury provides a way to add modern capabilities to those libraries and by doing so, Mercury allows you to choose your sauce. You can opt-in to supported engines, currently Motion and Anime JS V4 are supported. Feel free to open an issue on which animation library you would like Mercury to support or even open a PR.

Disclaimer ⚠️

While this is the general Mercury syntax and way of writing the initial, animate and transition parts of the animation, it is important to notice that inside any of those, the supported features depend on your core, for more information on what is supported or not check your engine of choice documentation:

  • Motion: Motion Website
  • AnimeJS: We support AnimeJS version 4 which is not yet public. As soon as it is, we will update this.
  • GSAP: GSAP Website

Structure

Animation properties vary depending on the engine but current engines support most of CSS properties,transforms, values and a lot of similar features, the syntax is pretty similar in all of the engines.

However Mercury defines a common API so that you don’t need to change the way you code depending on the engine. Mercury enables animations using the use:mercury directive. With the initial, animate, and transition properties, you can define how elements enter, transform, and behave during their lifecycle.

<div
  use:mercury={{
    initial: { opacity: 0, scale: 0 },
    animate: { opacity: 1, scale: 0.5 },
    transition: { duration: 1, delay: 0.2, ease: 'spring' }
  }}
>
  Animated Element
</div>

Initial

Defines the element’s initial state before the animation starts.

initial: { opacity: 0, scale: 0 }

Animate

Specifies the final state of the element after the animation.

animate: { opacity: 1, scale: 0.5 }

Transition

Controls the timing and behavior of the animation. Supported properties:

  • duration: Time in seconds the animation takes.
  • delay: Time before the animation starts.
  • ease: Easing function, such as linear, ease, spring, etc.
transition: { duration: 1, delay: 0.2, ease: 'spring' }

Example

<div
  use:mercury={{
    initial: { x: -100 },
    animate: { x: 0 },
    transition: { duration: 0.5, ease: 'easeOut' }
  }}
>
  Slide-in Animation
</div>