WIP~
A simple and straightforward animation library to enable CSS based animations on scroll, as soon as the elements become visible by the user.
Built with and how does it work
Options and how to customize them
Install VagaJS via a packet manager, such as npm:
npm install vagajs
Then import it in your javascript build:
import * as vaga from "vagajs/build/vaga.min.js";
and the CSS aswell:
import "vagajs/build/vaga.min.css"; //or add it in your CSS workflow
Now to run it simply start VagaJS somewhere in your javascript build:
vaga.start();
VagaJS has a set of default options to make it work right off the bat, however you can customize the options easily, more info in the documentation section.
VagaJS can work by simply adding its CSS classes on HTML elements once you've installed, imported it in your web project and started it.
Let's say you want to play a fade in animation on an element, here's how it works:
<div class="vaga-fade-in" style="background:lime;">Hello there!</div>
Here's how the VagaJS CSS classes work:
.vaga-<property>-<direction>
property: there are currently 3 properties, which are fade, move and opacity.
direction: there are 4 directions, which are in, out, left and right. (The opacity property has no directions!)
fade-in: .vaga-fade-in
fade-out: .vaga-fade-out
fade-left: .vaga-fade-left
fade-right: .vaga-fade-right
move-in: .vaga-move-in
move-out: .vaga-move-out
move-left: .vaga-move-left
move-right: .vaga-move-right
opacity: .vaga-opacity
Both fade and fade animations have a default transform length of 40px (20px on mobile), to customize this option you need to add a dataset, with vsize as the datataset property and an integer number as the value.
example: <div class="vaga-move-right" data-vsize="60"></div>
However you may want to have different animations on different viewports: that's why there are responsive utils in VagaJS.
Want to have a fade-in on an element when it's viewed in a mobile device and then replacing that animation with a fade-left when viewed on bigger viewports?
<div class="vaga-fade-in vaga-fade-left--md" style="background:lime;">Fade-in on mobile, fade-left on tablet and desktop</div>
These responsive util classes are mobile-first and work as follow:
.vaga-<property>-<direction>--<breakpoint>
Breakpoints are md (min-width: 992px) and lg (min-width: 1400px), here's another example:
.vaga-move-right--lg
To unload animations after the element is no longer visible.
.vaga-unload
Sometimes you want to have a bit of delay between animations, and for this issue VagaJS comes with a delay util:
.vaga-delay-<value>
This util will apply a delay based on its value, where the values are 1, 2, 3 and 4.
.vaga-delay-0-5 - will apply a delay of duration * 0.5. duration is an option, and its default is 0.375s, so this util will apply a delay of half of that value.
.vaga-delay-1 - will apply a delay of duration * 1 (which would be 0.375s).
.vaga-delay-1-5 - will apply a delay of duration * 1.5 (which would be 0.375s * 1.5).
.vaga-delay-2 - will apply a delay of duration * 2 (which would be 0.375s * 2).
And so on, up to .vaga-delay-6, which is duration * 6.
.vaga-will - applies will-change: transform; for smoother animations, MDN reference.
.vaga-block - trick to have smooth animations and transitions only when the window is loaded, add this to the parent/grandparent element such as the body.
This library is built on Intersection Observer API, which detects when an element is being viewed by the user.
By adding the VagaJS classes to your HTML elements, you assign an observer to them, detecting when they are visible, enabling and kicking off the animations.
VagaJS has a set of default options, which are the following:
root - default value is null, this is an IntersectionObserver's parameter.
rootMargin - default value is 0px, this is an IntersectionObserver's parameter.
threshold - default value is 0.25, this is an IntersectionObserver's parameter.
targets - default value is document.querySelectorAll("[class*='vaga-'"), this is an IntersectionObserver's parameter.
duration - default is 0.375s, CSS transition-duration.
timingFunction - default is ease-in, CSS transition-timing-function (can accept cubic-bezier() functions).
To customize these options, simply do like this:
var options = { threshold: 0.15, duration: 0.75, timingFunction: "linear" }
vaga.start(options)
VagaJS works on the latest versions of Chrome, Firefox, Edge and Safari.
lotrekagency/vagajs is licensed under the MIT License.
Check the repo's issues tab