aos

Animate on scroll library

26,486

2,571

26,486

359

View on GitHub View on NPM

Top Related Projects

animate.css

80,541

🍿 A cross-browser library of CSS animations. As easy to use as an easy thing.

WOW

9,901

Reveal CSS animation as you scroll down a page

scrollreveal

22,330

Animate elements as they scroll into view.

Quick Overview

AOS (Animate On Scroll) is a lightweight JavaScript library that allows you to animate elements as you scroll down the page. It provides a simple way to add CSS animations to your website, triggered when elements come into view during scrolling.

Pros

Easy to use with minimal setup required
Supports various animation styles out of the box
Highly customizable with options for duration, easing, and offset
Works well with responsive designs and mobile devices

Cons

May impact performance on pages with many animated elements
Limited to scroll-based animations only
Requires JavaScript to function, which may not be ideal for all use cases
Some users may find excessive animations distracting or annoying

Code Examples

Basic usage:

<div data-aos="fade-up">
  This element will fade up as you scroll down
</div>

Customizing animation duration:

<div data-aos="fade-up" data-aos-duration="3000">
  This element will fade up over 3 seconds
</div>

Using different animation types:

<div data-aos="flip-left">
  This element will flip from left to right
</div>

Delaying animation start:

<div data-aos="zoom-in" data-aos-delay="300">
  This element will zoom in after a 300ms delay
</div>

Getting Started

Include AOS in your project:

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

Initialize AOS in your JavaScript:

document.addEventListener('DOMContentLoaded', function() {
  AOS.init();
});

Add data-aos attributes to elements you want to animate:

<div data-aos="fade-up">Animate me!</div>

That's it! Your elements will now animate as you scroll down the page.

Competitor Comparisons

animate.css

80,541

🍿 A cross-browser library of CSS animations. As easy to use as an easy thing.

Pros of Animate.css

Simpler implementation with pure CSS animations
Wider range of pre-defined animations
Easier to customize individual animations

Cons of Animate.css

Lacks scroll-based triggering functionality
May require additional JavaScript for more complex animations
Can be less performant for large-scale animations

Code Comparison

AOS:

<div data-aos="fade-up" data-aos-duration="3000">
  This element will fade up
</div>

Animate.css:

<div class="animate__animated animate__fadeIn">
  This element will fade in
</div>

Key Differences

AOS focuses on scroll-based animations, while Animate.css provides general-purpose CSS animations
AOS requires JavaScript, whereas Animate.css is purely CSS-based
AOS offers more control over animation timing and triggers, while Animate.css is simpler to implement for basic animations

Use Cases

Choose AOS for scroll-triggered animations and more dynamic control
Opt for Animate.css for quick, simple animations or when avoiding JavaScript is preferred

Both libraries have their strengths and can be used together for more versatile animation implementations.

anime

49,575

JavaScript animation engine

Pros of anime

More versatile animation library, capable of complex animations beyond scroll-triggered effects
Smaller file size (16.8kB vs 27.9kB gzipped)
Better performance due to optimized JavaScript engine

Cons of anime

Steeper learning curve compared to AOS's simpler API
Requires more manual setup for scroll-based animations
Less focused on scroll-triggered animations, which is AOS's specialty

Code Comparison

AOS (scroll-based animation):

<div data-aos="fade-up" data-aos-duration="1000">
  Animate me on scroll
</div>

anime (general-purpose animation):

anime({
  targets: '.element',
  translateY: [-100, 0],
  opacity: [0, 1],
  duration: 1000,
  easing: 'easeOutQuad'
});

While AOS provides a declarative approach for scroll-based animations, anime offers a more programmatic and flexible solution for various animation needs. AOS is easier to implement for scroll animations, but anime provides greater control and versatility for complex animations across different scenarios.

WOW

9,901

Reveal CSS animation as you scroll down a page

Pros of WOW

Lightweight and simple to use, with minimal configuration required
Supports a wide range of animation styles out of the box
Easy to customize animations using CSS classes

Cons of WOW

Less actively maintained compared to AOS
Fewer advanced features and customization options
Limited documentation and community support

Code Comparison

WOW:

<div class="wow fadeIn">
  Content to animate
</div>

new WOW().init();

AOS:

<div data-aos="fade-in">
  Content to animate
</div>

AOS.init();

Both libraries use similar approaches for implementing animations, with WOW using CSS classes and AOS using data attributes. AOS offers more flexibility in configuration and animation options, while WOW provides a simpler implementation for basic animations.

WOW is a good choice for projects requiring quick and easy animation implementation, while AOS is better suited for more complex projects with advanced animation needs and ongoing development support.

scrollreveal

22,330

Animate elements as they scroll into view.

Pros of ScrollReveal

More customizable animation options, including callbacks and custom easing functions
Supports sequencing animations for complex reveal effects
Smaller file size, leading to faster load times

Cons of ScrollReveal

Less intuitive setup compared to AOS's data-attribute approach
Requires more JavaScript knowledge to implement advanced features
Limited built-in animation styles compared to AOS's diverse preset options

Code Comparison

ScrollReveal:

ScrollReveal().reveal('.element', {
    delay: 200,
    distance: '50px',
    origin: 'bottom',
    easing: 'cubic-bezier(0.5, 0, 0, 1)'
});

AOS:

<div data-aos="fade-up" data-aos-delay="200" data-aos-offset="300">
    Content to animate
</div>

Both libraries offer scroll-based animations, but they differ in implementation. ScrollReveal focuses on JavaScript configuration, providing more control over animation details. AOS uses a simpler data-attribute approach, making it easier for developers with less JavaScript experience to implement basic animations.

ScrollReveal excels in creating complex, sequenced animations and offers more fine-tuned control. However, it requires more setup and JavaScript knowledge. AOS, while less customizable, provides a wider range of built-in animation styles and is generally easier to implement for basic use cases.

Choose ScrollReveal for advanced, highly customized animations, and AOS for quick, easy-to-implement scroll effects with a variety of preset options.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

:exclamation::exclamation::exclamation: This is README for aos@next :exclamation::exclamation::exclamation:

For last stable release (v2) go here

ð Demo

ð Codepen Examples

ð To get a better understanding how this actually works, I encourage you to check my post on CSS-tricks.

â Installation

Basic

Add styles in <head>:

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

Add script right before closing </body> tag, and initialize AOS:

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

Using package managers

Install aos package:

yarn add aos@next
or npm install --save aos@next

Import script, styles and initialize AOS:

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

In order to make it work you'll have to make sure your build process has configured styles loader, and bundles it all correctly. If you're using Parcel however, it will work out of the box as provided.

ð¤ How to use it?

1. Initialize AOS:

AOS.init();

// 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

});

2. Set animation using `data-aos` attribute:

  <div data-aos="fade-in"></div>

And adjust behaviour by using data-aos-* attributes:

  <div
    data-aos="fade-up"
    data-aos-offset="200"
    data-aos-delay="50"
    data-aos-duration="1000"
    data-aos-easing="ease-in-out"
    data-aos-mirror="true"
    data-aos-once="false"
    data-aos-anchor-placement="top-center"
  >
  </div>

See full list of all animations, easings and anchor placements

Anchor

There is also a setting that can be used only on per-element basis:

data-aos-anchor - element whose offset will be used to trigger animation instead of an actual one.

Examples:

<div data-aos="fade-up" data-aos-anchor=".other-element"></div>

This way you can trigger animation on one element, while you scroll to another - useful in animating fixed elements.

API

AOS object is exposed as a global variable, for now there are three methods available:

init - initialize AOS
refresh - recalculate all offsets and positions of elements (called on window resize)
refreshHard - reinit array with AOS elements and trigger refresh (called on DOM changes that are related to aos elements)

Example execution:

  AOS.refresh();

By default AOS is watching for DOM changes and if there are any new elements loaded asynchronously or when something is removed from DOM it calls refreshHard automatically. In browsers that don't support MutationObserver like IE you might need to call AOS.refreshHard() by yourself.

refresh method is called on window resize and so on, as it doesn't require to build new store with AOS elements and should be as light as possible.

JS Events

AOS dispatches two events on document: aos:in and aos:out whenever any element animates in or out, so that you can do extra stuff in JS:

document.addEventListener('aos:in', ({ detail }) => {
  console.log('animated in', detail);
});

document.addEventListener('aos:out', ({ detail }) => {
  console.log('animated out', detail);
});

You can also tell AOS to trigger custom event on specific element, by setting data-aos-id attribute:

<div data-aos="fade-in" data-aos-id="super-duper"></div>

Then you'll be able to listen for two custom events then:

aos:in:super-duper
aos:out:super-duper

Recipes:

Adding custom animations:

Sometimes built-in animations are just not enough. Let's say you need one box to have different animation depending on resolution. Here's how you could do it:

[data-aos="new-animation"] {
  opacity: 0;
  transition-property: transform, opacity;

  &.aos-animate {
    opacity: 1;
  }

  @media screen and (min-width: 768px) {
    transform: translateX(100px);

    &.aos-animate {
      transform: translateX(0);
    }
  }
}

Then use it in HTML:

<div data-aos="new-animation"></div>

The element will only animate opacity on mobile devices, but from 768px width it'll also slide from right to left.

Adding custom easing:

Similar to animations you can add custom easings:

[data-aos] {
  body[data-aos-easing="new-easing"] &,
  &[data-aos][data-aos-easing="new-easing"] {
    transition-timing-function: cubic-bezier(.250, .250, .750, .750);
  }
}

Customizing default animations distance

Default distance for built-in animations is 100px. As long as you're using SCSS though, you can override it:

$aos-distance: 200px; // It has to be above import
@import 'node_modules/aos/src/sass/aos.scss';

You have to however configure your build process to allow it to import styles from node_modules beforehand.

Integrating external CSS animation library (e.g. Animate.css):

Use animatedClassName to change default behaviour of AOS, to apply class names placed inside data-aos on scroll.

<div data-aos="fadeInUp"></div>

AOS.init({
  useClassNames: true,
  initClassName: false,
  animatedClassName: 'animated',
});

The above element will get two classes: animated and fadeInUp. Using different combinations of the three above settings, you should be able to integrate any external CSS animation library.

External libraries however don't care too much about animation state before the actual animation. So if you want those elements to be not visible before scrolling, you might need to add similar styles:

[data-aos] {
  visibility: hidden;
}
[data-aos].animated {
  visibility: visible;
}

Caveats:

setting: `duration`, `delay`

Duration and delay accept values from 50 to 3000, with step 50ms, it's because those are handled by css, and to not make css longer than it is already I implemented only a subset. I believe those should cover most cases.

If not, you can write simple CSS that will add another duration, for example:

  body[data-aos-duration='4000'] [data-aos],
  [data-aos][data-aos][data-aos-duration='4000'] {
    transition-duration: 4000ms;
  }

This code will add 4000ms duration available for you to set on AOS elements, or to set as global duration while initializing AOS script. Notice that double [data-aos][data-aos] - it's not a mistake, it is a trick, to make individual settings more important than global, without need to write ugly "!important" there :)

Example usage:

  <div data-aos="fade-in" data-aos-duration="4000"></div>

Predefined options

Animations

Fade animations:
- fade
- fade-up
- fade-down
- fade-left
- fade-right
- fade-up-right
- fade-up-left
- fade-down-right
- fade-down-left
Flip animations:
- flip-up
- flip-down
- flip-left
- flip-right
Slide animations:
- slide-up
- slide-down
- slide-left
- slide-right
Zoom animations:
- zoom-in
- zoom-in-up
- zoom-in-down
- zoom-in-left
- zoom-in-right
- zoom-out
- zoom-out-up
- zoom-out-down
- zoom-out-left
- zoom-out-right

Anchor placements:

top-bottom
top-center
top-top
center-bottom
center-center
center-top
bottom-bottom
bottom-center
bottom-top

Easing functions:

linear
ease
ease-in
ease-out
ease-in-out
ease-in-back
ease-out-back
ease-in-out-back
ease-in-sine
ease-out-sine
ease-in-out-sine
ease-in-quad
ease-out-quad
ease-in-out-quad
ease-in-cubic
ease-out-cubic
ease-in-out-cubic
ease-in-quart
ease-out-quart
ease-in-out-quart

âQuestions

If you found a bug, have a question or an idea, please check AOS contribution guide and don't hesitate to create new issues.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of Animate.css

Cons of Animate.css

Code Comparison

Key Differences

Use Cases

Pros of anime

Cons of anime

Code Comparison

Pros of WOW

Cons of WOW

Code Comparison

Pros of ScrollReveal

Cons of ScrollReveal

Code Comparison

Convert designs to code with AI

README

:exclamation::exclamation::exclamation: This is README for aos@next :exclamation::exclamation::exclamation:

ð Demo

ð Codepen Examples

â Installation

Basic

Using package managers

ð¤ How to use it?

1. Initialize AOS:

2. Set animation using data-aos attribute:

Anchor

API

JS Events

Recipes:

Adding custom animations:

Adding custom easing:

Customizing default animations distance

Integrating external CSS animation library (e.g. Animate.css):

Caveats:

setting: duration, delay

Predefined options

Animations

Anchor placements:

Easing functions:

âQuestions

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days

ð Demo

ð Codepen Examples

â Installation

ð¤ How to use it?

2. Set animation using `data-aos` attribute:

setting: `duration`, `delay`

âQuestions