Guide · Open source

How to use AOS: install, add scroll animations and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

AOS (Animate On Scroll) is an MIT-licensed JavaScript and CSS library that animates elements when they scroll into view. This guide shows you how to install it, pick an animation with a data-aos attribute, tune timing and triggers, and handle a few common edge cases. You do not need custom scroll code to get started.

AOSmichalsnik/aos · ★ 28k · MIT Install options & downloads

Quick start

1Install the package. Run npm install --save aos@next or yarn add aos@next, or include the CDN files from the README in your HTML.
2Include the styles. Load aos.css in the head of your page, or import aos/dist/aos.css in your build.
3Initialize AOS. Add AOS.init() after the script loads, or import AOS and call AOS.init() in your build.
4Add data-aos to elements. Put data-aos="fade-up" or another built-in animation name on the HTML elements you want to animate.
5Tune per-element settings. Add data-aos-delay, data-aos-duration, data-aos-easing or other data-aos-* attributes where you need different timing.
6Check the result in a browser. Scroll the page and confirm each element animates in as expected, then adjust offset or anchor settings if needed.

Install AOS on a plain HTML page or with a package manager

For a plain HTML page, add the stylesheet in the head and the script right before the closing body tag, then initialize AOS. The README loads both files from unpkg.

If you use a build process, install the package with npm or yarn. The README describes this as the aos@next version. You then import the script and styles and call AOS.init(). Your build must include a styles loader. If you use Parcel, it works out of the box.

Plain HTML: include aos.css in the head and aos.js before the closing body tag.
Package manager: install aos@next, then import AOS and aos/dist/aos.css.

npm install --save aos@next

# or
yarn add aos@next

import AOS from 'aos';
import 'aos/dist/aos.css';
AOS.init();

Add an animation with the data-aos attribute

Put a data-aos attribute on any HTML element to choose its animation, such as fade-in. To adjust behaviour for that element, add data-aos-* attributes like offset, delay, duration, easing, mirror, once and anchor-placement.

The README documents a data-aos-anchor setting that works only per element. It makes the element's trigger point come from another element, which is useful for animating fixed elements.

data-aos-delay and data-aos-duration accept values from 0 to 3000 in 50ms steps, according to the README's settings comments.
data-aos-anchor takes a selector, for example .other-element.

<div data-aos="fade-up" data-aos-duration="1000" data-aos-easing="ease-in-out"></div>

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

Set global options with AOS.init()

Call AOS.init() with an optional settings object to change defaults across the page. The README lists global options such as disable, startEvent, initClassName, animatedClassName and useClassNames, plus per-element defaults such as offset, delay, duration, easing, once, mirror and anchorPlacement.

The default offset is 120px, the default duration is 400ms, and the default easing is 'ease'. The default anchorPlacement is 'top-bottom'.

disable accepts 'phone', 'tablet', 'mobile', a boolean, an expression or a function.
once: false means the animation runs every time you scroll past. Set it to true to run it only once.

AOS.init({
  offset: 120,
  duration: 400,
  easing: 'ease',
  once: false,
  mirror: false,
  anchorPlacement: 'top-bottom'
});

Use the AOS API and events

AOS exposes a global object with three methods: init, refresh and refreshHard. AOS calls refresh on window resize. By default it watches for DOM changes and calls refreshHard when elements are added or removed.

AOS dispatches aos:in and aos:out events on the document. If you set data-aos-id on an element, you also get events named aos:in:your-id and aos:out:your-id.

AOS.refresh() recalculates offsets and positions.
AOS.refreshHard() rebuilds the list of AOS elements and then refreshes.
Browsers without MutationObserver, such as IE, may need you to call AOS.refreshHard() yourself.

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

Create a custom animation or connect another CSS library

The README shows a recipe for custom animations. You write CSS for a new data-aos value, set opacity and transform rules, and use the aos-animate class as the state that starts the animation. You can change the default distance of built-in animations, which is 100px, by setting $aos-distance in SCSS before importing the stylesheet.

To use another CSS animation library such as Animate.css, set useClassNames to true, set initClassName to false and set animatedClassName to 'animated'. The element then receives the class names from data-aos as classes on scroll. You may also need visibility rules to hide elements before they animate.

Custom easings are added with a cubic-bezier value in CSS.
Duration and delay values outside the built-in subset need custom CSS, according to the README caveats.

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

What people use it for

Adding fade-in or fade-up reveals to sections of a marketing or landing page.
Setting scroll animations with HTML attributes instead of writing scroll listeners.
Prototyping scroll-based motion in a browser before building it into a product.
Animating a fixed element by using data-aos-anchor to trigger it from another element.
Connecting an existing CSS animation library to scroll triggers through useClassNames.

Frequently asked questions

Is AOS free to use?

AOS is released under the MIT licence, according to the repository summary. The MIT licence generally allows use in commercial and personal projects, but read the licence file in the repository for the exact terms.

How do I install AOS?

Run npm install --save aos@next or yarn add aos@next. For a plain HTML page, you can instead include the aos.css and aos.js files from unpkg as shown in the README.

Does AOS work in Internet Explorer?

The README says some features need MutationObserver, and IE may need manual refresh calls. Call AOS.refreshHard() yourself in browsers without MutationObserver, and test your target browsers before relying on it.

Why are my AOS animations not running?

Check that you called AOS.init() and that the aos.css stylesheet loads. If your build process does not handle CSS imports, the styles will not apply. The README also notes that with a bundler you need a styles loader configured.

What are the alternatives to AOS?

The repository lists ScrollReveal, GSAP ScrollTrigger, Motion (formerly Framer Motion) and WOW.js as comparable projects. AOS is aimed at simple, attribute-based reveals, while the README says it does not cover complex timeline animation.

Which version of AOS should I use?

The README describes itself as the aos@next version and links to v2 as the last stable release. Check the repository for the current release status before choosing a version for production.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

AOS suits front-end developers and designers who want simple scroll reveal effects on a landing page or plain HTML site, set up with HTML attributes. Pick a different tool if you need complex timeline animation, strong support for older browsers like IE, or an actively maintained release, since the README's latest push shown is from March 2024 and no latest release is listed.

Install options & downloads