leo-animate.js

⚠️ Warning

This readme was written primarily with Google Translate. I'll be happy if you make an exception for any grammatical errors!

🔎 Introduction

leo-animate.js is a JavaScript module that uses the IntersectionObserver API to apply animations on the page according to the elements are visible in the viewport.

leo-animate.js is a modern alternative to apply scroll animations and page enter animations asynchronously, ensuring that the user sees the defined transitions.

🚀 Get started

This repository is distributed with the npm package manager. Perform the Installation of Node.js which already has npm as default package manager.

Installation

npm i leo-animate.js

Include the CSS

At the top of your stylesheet, include:

@import "/node_modules/leo-animate.js/dist/leo-animate.css"
layer(leo-animate.js);

layer() is just to create a new cascade layer to identify the styles applied by leo-animate.js. You must delete it in production or if you are importing the styles with SASS.

Include the JavaScript

At the top of your module-like script file, include:

import LeoAnimate from "/node_modules/leo-animate.js/dist/leo-animate.js"

Instantiate the class

new LeoAnimate();

You might want to refer to some usage examples with React!

Usage

Ready! You can already use the data-animate attribute on the element you want to animate with the default values: fadeDown, fadeUp, fadeRight and fadeLeft.

<h1 data-animate="fadeRight">
    leo-animate.js
</h1>

Responsive attributes are also available: sm, md, lg, xl, xxl.

<p data-animate="fadeRight"
data-animate-lg="fadeDown">
    leo-animate.js
</p>

NOTE: If you want to use only the responsive attributes, you must specify at least data-animate with no value to apply the animations.

💻 Features

Discard the onscroll event

As leo-animate.js uses the IntersectionObserver API to observe when an element is visible in the viewport and only then execute something, the onscroll event is completely unnecessary, making it unnecessary to execute a function several times according to the user's scroll.

Ensure animation visibility

Using IntersectionObserver also ensures that the animation does not run if the user enters the page but minimizes the window or switches tabs in their browser.

Fully Responsive

leo-animate.js uses a custom attribute called data-animate to apply the animations. This attribute can contain several variations for specific breakpoints, making it possible to use different animations depending on the desired media query.

Setting animations in HTML:

<h1 class="app__title"
data-animate="fadeRight"
data-animate-md="fadeDown">
    leo-animate.js
</h1>

CSS compiled:

[data-animate=fadeRight] {
    transform: translate3d(-15px, 0, 0);
    opacity: 0;
}
@media (max-width: 767.98px) {
    [data-animate-md=fadeDown] {
    transform: translate3d(0, -15px, 0);
    opacity: 0;
    }
}

This is an example of using the default settings of leo-animate.js, but you can configure both the media query itself and the name of the media query to use in the (data-animate-custom) attribute.

Highlight each element

If there is more than one visible element where the animation would run at the same time as another element, a delay is automatically applied to the animation.

In the gif below, for example, a specific delay was NOT manually set for the animation of each element:

Adaptable to reduced motion preferences

leo-animate.js ensures that none of the animations are styled and the JavaScript itself is omitted with those who prefer to override animations.

📋 Builder Options

The LeoAnimate constructor receives an optional object as an argument that allows configuring how the animations will occur. If you want to configure other types of animations or customize breakpoints, configure SASS from leo-animate.js.

In the LeoAnimate object, the following properties are available:

| Property | Type | Description | | ------------------------- | --------- | ----------- | | infinite | boolean | Sets whether animations will recur after the page has been scrolled up. The default value is false. | multipleElementsDelay | number | Sets a delay in milliseconds for the animation to occur between elements that are displayed at the same time. Setting a positive number allows you to use a sync-special-attribute on elements. The default value is 400. | transitions | object | Object containing the CSS transition properties that will be applied to all elements. See customizing transitions.

Sync special attribute

data-animate-sync e data-animate-id

When the constructor's multipleElementsDelay property has a positive number, it is possible to use the data-animate-sync attribute to apply the same animation delay to an element as another element.

Use data-animate-id to give a unique name to the element you want to copy the animation delay. Now just give the element that you are going to synchronize the delay with the same id as the value of data-animate-sync.

To be clearer, consider the following example:

Now see the same example where the first element / cell of each column has data-animate-id with a unique id and each element below has data-animate-sync pointing to the respective id.

Customizing transitions

transitions e data-animate-{transition}

The transitions object of the constructor applies the transitions mentioned below to all elements. However, you can also use the same key names in the data-animate attribute on a specific element to override the global transition defined in the constructor.

All values are given a string that must represent a valid CSS value.

| Property | Equivalent attribute | Description | | -----------------| -----------------------| ----------- | | duration | data-animate-duration | Sets the time the animation(s) takes to complete. The default value is "600ms". | timingFunction | data-animate-timingFunction | Defines the timing function of the animation(s). The default value is "ease".