This readme was written primarily with Google Translate. I'll be happy if you make an exception for any grammatical errors!
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.
This repository is distributed with the npm package manager. Perform the Installation of Node.js which already has npm as default package manager.
npm i leo-animate.js
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.
At the top of your module-like script file, include:
import LeoAnimate from "/node_modules/leo-animate.js/dist/leo-animate.js"
new LeoAnimate();
You might want to refer to some usage examples with React!
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.
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.
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.
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.
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:
leo-animate.js ensures that none of the animations are styled and the JavaScript itself is omitted with those who prefer to override animations.
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. |
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.
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" . |