Aos

Animate on Scroll, reimagined.
A modern, zero-dependency AOS replacement with full TypeScript support.

Intro

Aos is a lightweight, TypeScript-first scroll animation library powered by IntersectionObserver. It's a drop-in replacement for the original AOS library — actively maintained, with more features and zero dependencies.

If you've used AOS before, you'll feel right at home. If you haven't, here's what you get:

• Zero dependencies — uses only the DOM and IntersectionObserver
• Full TypeScript support — fully typed config, callbacks, and return values
• Anchor support — trigger animations based on a different element's visibility
• Mirror mode — reverse animations when elements leave the viewport
• Per-element overrides — set data-aos-duration, data-aos-easing, and data-aos-delay on individual elements
• Mobile control — disable animations on mobile devices or below a minimum window width
• Custom disable logic — pass your own function to decide whether to initialise
• Clean teardown — destroy() disconnects all observers and removes all added classes/attributes

Table of contents

• Quickstart
• Configuration
• HTML attributes
• Anchors
• Callbacks
• Disabling animations
• Cleanup
• Framework examples
• API reference
• Contributor docs
• License

Quickstart

Install:

bun add @nitlix-hq/aos

Other package managers:

pnpm add @nitlix-hq/aos
npm i @nitlix-hq/aos

1) Add data-aos attributes to your HTML

Apply the data-aos attribute with the name of the animation you want:

<div data-aos="fade-up">I animate when scrolled into view</div>
<div data-aos="fade-left" data-aos-duration="500">I'm faster</div>

2) Include AOS CSS

You'll need to include the AOS stylesheet for the built-in animation classes. You can use the original AOS CSS or write your own — Aos toggles the aos-init and aos-animate classes, so any CSS that targets those will work.

3) Initialise Aos

import init from "@nitlix-hq/aos";

const aos = init({
    duration: 800,
    easing: "ease-in-out",
    mirror: false,
});

That's it. Every element with data-aos is now observed and will animate when it enters the viewport.

4) Clean up when done

aos.destroy();

Configuration

Pass a config object to init(). All fields are optional:

Option	Type	Default	Description
duration	number	1000	Animation duration in milliseconds
easing	string	"ease-in-out"	CSS easing function
delay	number	0	Delay before the animation starts (ms)
mirror	boolean	false	Reverse animations when elements scroll out of view
offsetEnter	number	0	Offset (px) from the top of the viewport for triggering enter
offsetExit	number	0	Offset (px) from the bottom of the viewport for triggering exit
mobile	boolean	false	Disable animations on mobile devices (ignored if disableInitFunc is set)
minWindowWidth	number	0	Minimum window width for animations to be enabled (ignored if disableInitFunc is set)
callback	(element, status, observer, entry) => void	—	Called when an element enters or exits the viewport
disableInitFunc	() => boolean	—	Custom function to determine whether Aos should be disabled

HTML attributes

These attributes can be set on individual elements to override global config:

Attribute	Description
data-aos	The animation name (required)
data-aos-duration	Override animation duration (ms)
data-aos-easing	Override CSS easing function
data-aos-delay	Override animation delay (ms)
data-aos-anchor	CSS selector of an anchor element

If a per-element attribute is already set, Aos won't overwrite it with the global default.

Anchors

By default, Aos observes the animated element itself. With data-aos-anchor, you can trigger an animation based on a different element entering the viewport:

<div id="trigger-point">Scroll past me...</div>
<div data-aos="fade-up" data-aos-anchor="#trigger-point">
    I animate when #trigger-point is visible
</div>

If the anchor selector is invalid or not found, Aos falls back to observing the element itself.

Callbacks

The callback option fires every time an observed element enters or exits the viewport:

init({
    callback: (element, status, observer, entry) => {
        console.log(element, status); // "enter" or "exit"
    },
});

Exit callbacks only fire when mirror is true.

Disabling animations

Mobile detection

init({ mobile: false }); // disables on mobile user agents

Minimum window width

init({ minWindowWidth: 768 }); // disables below 768px

Custom logic

init({
    disableInitFunc: () => {
        return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
    },
});

When disabled, Aos strips all data-aos related attributes from elements so they render in their final state without animation.

Cleanup

init() returns an object with a destroy() method. Calling it:

1. Disconnects all IntersectionObserver instances
2. Removes aos-init and aos-animate classes from all managed elements
3. Removes any attributes that Aos added (preserves attributes that were already present)

const aos = init();

// Later (e.g. on route change in an SPA):
aos.destroy();

Framework examples

React

import { useEffect } from "react";
import init from "@nitlix-hq/aos";

function App() {
    useEffect(() => {
        const aos = init({ duration: 800, mirror: true });
        return () => aos.destroy();
    }, []);

    return <div data-aos="fade-up">Hello</div>;
}

Svelte

<script>
    import { onMount, onDestroy } from "svelte";
    import init from "@nitlix-hq/aos";

    let aos;
    onMount(() => {
        aos = init({ duration: 800 });
    });
    onDestroy(() => aos?.destroy());
</script>

<div data-aos="fade-up">Hello</div>

Vanilla JS

<script type="module">
    import init from "@nitlix-hq/aos";
    init({ duration: 1000, easing: "ease-out" });
</script>

<div data-aos="fade-up">Hello</div>

API reference

init(config?)

Initialises Aos. Scans the DOM for [data-aos] elements, sets up IntersectionObserver instances, and applies default attributes.

Parameters:

Name	Type	Description
config	Config	Optional config object

Returns: { destroy: () => void }

Config

interface Config {
    duration?: number;
    easing?: string;
    callback?: (
        element: Element,
        status: "enter" | "exit",
        observer: IntersectionObserver,
        entry: IntersectionObserverEntry,
    ) => void;
    mirror?: boolean;
    disableInitFunc?: () => boolean;
    delay?: number;
    offsetEnter?: number;
    offsetExit?: number;
    mobile?: boolean;
    minWindowWidth?: number;
}

Contributor docs

• Implementation & extension guide: FOR_AGENTS.md

License

MIT