TopGit
GitHub Repo Review

AOS: a CSS-driven scroll animation library

ATopGit review image for michalsnik/aos
Review by Topgit.dev for michalsnik/aos, with GitHub repository stats and README context.
Quick verdict

AOS is a lean animate-on-scroll library: add a data-aos attribute to an element and it fades, slides, flips, or zooms into view once it scrolls past a trigger point. The trade-off is honest: plain CSS transitions replace a JS animation engine, so there's less to debug but also less choreography than timeline-based tools. Good fit if you just want scroll-triggered fades and slides without a JS animation dependency; skip it if your design calls for staggered or physics-based sequences, since AOS has no timeline API for that.

Stars
★ 28.1k
Forks
⑂ 2.6k
Language
JavaScript
License
MIT
Topic
—
Updated
Mar 2024
Homepage
—
GitHub

What is AOS?

AOS (Animate On Scroll) is a JavaScript library that triggers CSS animations as elements enter or leave the viewport while a page scrolls. You add a data-aos attribute naming a built-in animation, like fade-up, zoom-in, or flip-left, and AOS's own scroll listener toggles a class that fires the matching CSS transition, without pulling in an animation framework underneath it.

Installing AOS via npm or CDN

The current README targets the aos@next pre-release branch; the last stable release (v2) has its own README on the v2 tag, so check which one you actually want before copying commands. For a plain HTML page, add the stylesheet with <link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" /> in <head>, then a script tag pointing at https://unpkg.com/aos@next/dist/aos.js right before the closing </body>, followed by AOS.init(). With a package manager, run npm install --save aos@next (or yarn add aos@next), then import AOS from 'aos'; import 'aos/dist/aos.css'; and call AOS.init(). The README warns that npm installs need a configured styles loader in your build process to bundle the CSS correctly; Parcel is called out as working without extra config, other bundlers aren't guaranteed to.

Initializing AOS with configuration options

AOS.init() works with zero arguments using its defaults. Nothing else is required. You can also pass a settings object to override them globally. One group is global-only: disable (skip init on 'phone', 'tablet', 'mobile', a boolean, or a function), startEvent (default 'DOMContentLoaded'), initClassName and animatedClassName (the classes AOS applies before and during animation), useClassNames, disableMutationObserver, debounceDelay (default 50ms on resize), and throttleDelay (default 99ms on scroll). A second group, offset (default 120px), delay (0-3000ms), duration (default 400ms), easing (default 'ease'), once, mirror, and anchorPlacement (default 'top-bottom'), sets the defaults but can be overridden per element with matching data-aos-* attributes, so a global AOS.init({ duration: 600 }) and a single data-aos-duration='1200' on one element can coexist.

Available animations, easings, and anchor placements

  • ✓Four animation families, fade, flip, slide, and zoom, each with directional variants like fade-up-right or zoom-out-left, set purely through the data-aos value.
  • ✓Nine anchor-placement options (e.g. top-bottom, center-center, bottom-top) control which part of the element and viewport has to align before the animation fires.
  • ✓A long list of named easing functions, linear plus in/out/in-out variants of back, sine, quad, cubic, and quart curves, selectable per element via data-aos-easing.
  • ✓Three public API methods, init, refresh, and refreshHard, with refresh recalculating element offsets on resize and refreshHard rebuilding the tracked element list after DOM changes.
  • ✓A built-in MutationObserver watches the DOM and calls refreshHard automatically when AOS-tracked elements are added or removed, so single-page apps don't need to call it by hand in modern browsers.
  • ✓data-aos-anchor lets one element's scroll position trigger another element's animation, which the README calls out as useful for animating fixed elements.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history ↗

Per-element animation control with data-aos attributes

  • •Overriding duration, delay, easing, or anchor placement on a single element with data-aos-duration, data-aos-delay, data-aos-easing, and data-aos-anchor-placement, without touching the global AOS.init() config.
  • •Triggering an animation on a fixed or off-screen element based on a different element's scroll position, using data-aos-anchor.
  • •Playing an animation once instead of every time an element re-enters the viewport, with data-aos-once='true' or the global once setting.
  • •Reversing an animation when an element scrolls back past its trigger point, via the mirror setting.
  • •Writing a fully custom animation in CSS, targeting [data-aos='name'] and its .aos-animate state, for effects the built-in presets don't cover.
  • •Listening for aos:in and aos:out DOM events, or their data-aos-id-scoped named versions, to run JavaScript side effects on the same scroll triggers.

Strengths

  • ✓Adding scroll animations to a static HTML page via the CDN script and stylesheet tags takes one AOS.init() call, no bundler or component framework required.
  • ✓Almost every setting (offset, delay, duration, easing, anchor, once, mirror) can be overridden per element via data-aos-* attributes, not just globally in AOS.init().
  • ✓The animation runs as a plain CSS transition, so there's no animation-engine indirection to debug: the aos-animate class either applied the transition-end state or it didn't.
  • ✓aos:in and aos:out events, plus data-aos-id-scoped named variants, give you a hook into the same scroll triggers for non-visual side effects instead of writing separate IntersectionObserver code.

Limitations: duration step values and browser quirks

  • △Duration and delay only accept values from 0 to 3000 in 50ms steps; the README says this is because both are implemented in CSS, so finer control means writing extra CSS transition rules yourself.
  • △Browsers without MutationObserver support, like older IE, don't get automatic detection of new AOS elements; you have to call AOS.refreshHard() by hand after DOM changes.
  • △The default branch's README documents aos@next, a pre-release line separate from the last stable v2 tag, so first-time installers have to pick the right one before following any instructions here.
  • △Installing via npm doesn't work out of the box in every bundler; the README says you must configure a styles loader to bundle the CSS correctly, and only calls out Parcel as working without that setup.

AOS vs ScrollReveal and other scroll animation libraries

ScrollReveal — the closest direct competitor: same 'add an attribute or selector, get a scroll-triggered animation' pitch, but configured through a JS options object per selector instead of data-aos-* HTML attributes.react-motion — for React apps that would rather drive animations from component state via a physics-based JS API than manage data-aos-* markup, combining it with your own scroll trigger instead of AOS's built-in one. ↗Rolling your own with the native Intersection Observer API — more code to write and maintain, but no external script or CSS file to load for what can be a handful of one-off fade-ins.

Frequently asked questions about AOS

Does AOS work with Internet Explorer?

AOS works in Internet Explorer, but with one caveat: IE lacks MutationObserver support, so AOS can't automatically detect elements added to the page after load. In IE, call AOS.refreshHard() manually whenever the DOM changes so newly added data-aos elements get picked up.

How do I add custom animations beyond the built-in ones in AOS?

Custom animations in AOS are plain CSS: write a rule for [data-aos="your-name"] with a matching &.aos-animate state defining the animated end values, then set data-aos="your-name" on the element. AOS only adds and removes the aos-animate class; the transition itself is CSS you write yourself.

Can AOS animate elements only once, not on every scroll up?

Yes. AOS has a once setting (default false) that, when set to true either globally in AOS.init({ once: true }) or per element with data-aos-once="true", plays the animation a single time on the way down instead of re-triggering every time the element re-enters the viewport.

How do I integrate AOS with Animate.css?

AOS integrates with Animate.css by setting useClassNames: true, initClassName: false, and animatedClassName: 'animated' in AOS.init(), then putting the Animate.css class name, like fadeInUp, directly inside data-aos. AOS then applies both the animated and Animate.css classes on scroll instead of its own built-in transitions.

Why are my AOS animations not triggering?

AOS animations that don't trigger are almost always a setup issue: AOS.init() was never called, the aos.css stylesheet wasn't loaded, or the bundler's style loader isn't configured. The README notes you must have a styles loader in your build process for the animations to apply, Parcel being the one bundler that works without extra config.

The problem it solves

Adding 'fade in as you scroll' effects to a static site usually means either writing your own IntersectionObserver-plus-classList boilerplate for every element, or pulling in a full animation framework just to trigger transitions at a scroll position. AOS closes that specific gap: one data-aos attribute plus a single AOS.init() call replaces the boilerplate, while the animation itself stays plain CSS instead of framework-specific syntax.

Who should try it — and who should skip

AOS fits developers shipping a static marketing page, landing page, or portfolio in plain HTML/CSS who want fade, slide, or zoom effects without adopting a full animation framework; the CDN path covers that in two script tags and one AOS.init() call. It also fits teams already on npm/webpack willing to configure a CSS loader once, per the README's setup note. It's a weaker fit inside a React or Vue app where component state already drives enter/exit rendering, since wiring data-aos attributes through JSX or templates fights the framework instead of using it, and something like react-motion sits closer to how those apps already work. It also isn't the right tool for staggered, sequenced, or physics-based motion; the CSS-transition model tops out at one class change per trigger point.

Source & attribution

Facts and quotes attributed to the michalsnik/aos GitHub repository (github.com/michalsnik/aos), primarily its README covering the aos@next branch.

GitHub data · last synced Aug 15, 2026Reviewed by Henry
← Back to TopGit

Curious whether aos is right for you?

Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about aos.

GitHub