how to use aos.js in your project

Today we take a look at aos.js - the Animate On Scroll library created by Michal Sajnóg. This Library is small, easy to use and perfect to create simple singlepages.

install/load AOS

If you are working with node.js you can install AOS using NPM:

npm install --save aos@next

Or yarn:

yarn add aos@next

Import script, styles and initialize AOS:

import AOS from 'aos';
import 'aos/dist/aos.css'; // You can also use  for styles
// ..
AOS.init();

Or you can use a CDN service to load aos.css inside your <head> tags:

<link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />

And load aos.js before your closing </body> tag and initialize AOS there.

<script src="https://unpkg.com/aos@next/dist/aos.js">
<script>
    AOS.init();
</script>

Initialize AOS

To initialize AOS we only need to call the init() method of the AOS object. As an optional argument we can pass a JSON object with some config parameters. Bellow you see the default values for the config object taken from the documentation:

// You can also pass an optional settings object
// below listed default settings
AOS.init({
  // Global settings:
  disable: false, // accepts following values: 'phone', 'tablet', 'mobile', boolean, expression or function
  startEvent: 'DOMContentLoaded', // name of the event dispatched on the document, that AOS should initialize on
  initClassName: 'aos-init', // class applied after initialization
  animatedClassName: 'aos-animate', // class applied on animation
  useClassNames: false, // if true, will add content of `data-aos` as classes on scroll
  disableMutationObserver: false, // disables automatic mutations' detections (advanced)
  debounceDelay: 50, // the delay on debounce used while resizing window (advanced)
  throttleDelay: 99, // the delay on throttle used while scrolling the page (advanced)
  

  // Settings that can be overridden on per-element basis, by `data-aos-*` attributes:
  offset: 120, // offset (in px) from the original trigger point
  delay: 0, // values from 0 to 3000, with step 50ms
  duration: 400, // values from 0 to 3000, with step 50ms
  easing: 'ease', // default easing for AOS animations
  once: false, // whether animation should happen only once - while scrolling down
  mirror: false, // whether elements should animate out while scrolling past them
  anchorPlacement: 'top-bottom', // defines which position of the element regarding to window should trigger the animation

});

animate our first element

AOS enables us to use custom data attributes to controll the behaviour of the animations on the HTML element, so we dont have to bother about extra javascript files to setup our animations. The only necessary parameter we have to set, to get a simple animation running, is the animation name. Luckily AOS ships with a lot predefined animations, e.g. "zoom-in". Let's give it a try:

See the Pen PggzKe by Samuel Weber (@AndTheGodsMadeLove) on CodePen.

change animation settings per element

Once AOS gets initiated, it will look for elements with one or more data-aos-* attributes inside the DOM. In our example we only used data-aos to set the animation name, but we have access to more data-attributes to controll the animation. The default values for the init() method show us the following parameters we can modify via data-aos-* attributes:

// Settings that can be overridden on per-element basis, by `data-aos-*` attributes:
offset: 120, // offset (in px) from the original trigger point
delay: 0, // values from 0 to 3000, with step 50ms
duration: 400, // values from 0 to 3000, with step 50ms
easing: 'ease', // default easing for AOS animations
once: false, // whether animation should happen only once - while scrolling down
mirror: false, // whether elements should animate out while scrolling past them
anchorPlacement: 'top-bottom', // defines which position of the element regarding to window should trigger the animation

For example, if we want to change the animation duration of an element, we can use the data-aos-duration attribute to set a value:

See the Pen AOS Example - change animation duration for a specific element by Samuel Weber (@AndTheGodsMadeLove) on CodePen.

With the combination of the predefined animations and the data attributes provided by AOS, we already can achieve a lot of fancy effects without any effort at all.

custom animations

However, if you need a custom animation, it can be done with ease. Let's add a custom animation to our example and start with the CSS first:

[data-aos="customAnimationName"] {
    opacity: 0;
    margin-left: -550px;  
    transform: rotate(90deg);
    transition-property: opacity, margin-left, transform;
}
[data-aos="customAnimationName"].aos-animate {
    opacity: 1;
    margin-left: 0;
    transform: rotate(0);
}

Now we are already good to go and can use the animation within the data attribute. Let's add some HTML:

<section class="customAnimations">
    <h2 data-aos="customAnimationName">custom</h2>
</section>

Scroll down in the codepen to trigger the custom animation:

See the Pen AOS Example - create a custom animation by Samuel Weber (@AndTheGodsMadeLove) on CodePen.

JavaScript events

AOS v3.0.0 aka aos@next ships with events, and you can even create your own custom events with a simple data attribute. Whenever one of your animations start, AOS dispatches and event named aos:in or aos:out. Let's try it and append some JavaScript to listen to them:

document.addEventListener('aos:in', ({ detail }) => {
    console.log(detail, 'animation to display element started');
});
document.addEventListener('aos:out', ({ detail }) => {
    console.log(detail, 'animation to hide element started');
});

See the Pen AOS Example - JavaScript events by Samuel Weber (@AndTheGodsMadeLove) on CodePen.

I'm pretty sure everyone knows where to find the console in his browser to test this snippet ;). Scroll between the sections and watch your console while the animations kick in.

custom JavaScript events

AOS provides a nice way to implement custom events for our HTML elements with another data attribute named data-aos-id.

<section class="customJsEvents">
    <h2 data-aos="fade-left" data-aos-id="customEventName">custom event</h2>
</section>

So we added the data-aos-id attribute with a value of customEventName to our HTML element and told AOS to dispatch two more events, named aos:in:customEventName and aos:out:customEventName, when an animation for the element starts. Let's add some listener to our example:

document.addEventListener('aos:in:customEventName', ({ detail }) => {
    console.log(detail, 'animation to display element with custom event started');
});
document.addEventListener('aos:out:customEventName', ({ detail }) => {
    console.log(detail, 'animation to hide element with custom event started');
});

And some CSS

.customJsEvents {
  background-color: rgb(194, 223, 227);
}
.customJsEvents h2 {
    color: rgb(92, 107, 115);
    background-color: rgb(157, 180, 192);
}

See the Pen AOS Example - create and listen to custom JavaScript event by Samuel Weber (@AndTheGodsMadeLove) on CodePen.

As we see, you can create some nice animations based on scrolling super easy with almost zero effort. Data attributes allow you to set up everything you need and still pass your validators. Overall I really enjoyed taking a look at AOS.
So long, Sam

comment successfully committed
Robert Brown 15.05.2019

Thank you for the fixed custom events. Saved my day! Best regards from Scotland

leave a comment:

please enter your first name above
please enter a valid email above
please enter your message before you send the form

connect

please enter your name
please enter a valid email above
please enter the subject for your request
please enter your message before you send the form
mail successfully committed