AOS (Animate On Scroll)

repository·next·Indexed 12 days ago

A lightweight JavaScript library that triggers CSS animations as elements enter the browser viewport during scrolling. Version 3.0.0-beta.6 allows for global configuration, per-element customization via data attributes, and custom animations and easings. Includes API methods like init(), refresh(), and refreshHard(), as well as support for external CSS animation libraries.

Tokens: 2K
Snippets: 7
Records: 8
Agent score: 49%

What's inside AOS

Integrate external CSS animation libraries (e.g., Animate.css)
next
You can use AOS to trigger external CSS animation libraries by configuring useClassNames, initClassName, and animatedClassName.
1. Set useClassNames: true so that the content of data-aos is applied as a class.
2. Set initClassName: false to prevent the default aos-init class.
3. Set animatedClassName to the class used by your library (e.g., 'animated').
Example Configuration
```
<div data-aos="fadeInUp"></div>
```
```
AOS.init({
  useClassNames: true,
  initClassName: false,
  animatedClassName: 'animated',
});
```
Note: Since external libraries might not handle the 'pre-animation' state, you may need to manually hide elements before they animate:
```
[data-aos] {
  visibility: hidden;
}
[data-aos].animated {
  visibility: visible;
}
```
https://github.com/michalsnik/aos/blob/next/README.md
Install AOS via CDN or Package Managers
next
You can install AOS using a simple CDN approach or via modern package managers like npm or yarn.
CDN Approach
Add the stylesheet in your <head> and the script before the closing </body> tag:
```
<link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />
<script src="https://unpkg.com/aos@next/dist/aos.js"></script>
<script>
  AOS.init();
</script>
```
Package Manager Approach
Install the package using npm or yarn:
```
yarn add aos@next
# or
npm install --save aos@next
```
Then import the library and its styles in your JavaScript entry point:
```
import AOS from 'aos';
import 'aos/dist/aos.css';

// ...

AOS.init();
```
Note: If using a bundler, ensure your build process is configured to handle CSS loaders. Parcel works out of the box.
```
npm install --save aos@next
```
https://github.com/michalsnik/aos/blob/next/README.md
Apply animations to HTML elements using data attributes
next
To animate an element, add the data-aos attribute with the desired animation name. You can further customize the behavior of specific elements using data-aos-* attributes.
Basic Usage
```
<div data-aos="fade-in"></div>
```
Advanced Per-Element Customization
Use data-aos-* attributes to override global settings for a specific element:
```
<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>
```
Using a Custom Anchor
Use data-aos-anchor to specify a different element whose offset should trigger the animation. This is useful for animating fixed elements based on the position of another element:
```
<div data-aos="fade-up" data-aos-anchor=".other-element"></div>
```
https://github.com/michalsnik/aos/blob/next/README.md

Create custom animations and easings

You can extend AOS by defining your own CSS animations and easing functions.

Custom Animations

Define a selector based on the data-aos attribute. Use the .aos-animate class to trigger the final state:

[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);
    }
  }
}

Custom Easings

To add a custom easing, target the data-aos-easing attribute:

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

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

  &.aos-animate {
    opacity: 1;
  }
}

Listen to AOS JS Events

AOS dispatches events on the document whenever an element animates in or out. You can listen to these globally or for specific elements.

Global Events

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

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

Specific Element Events

To listen for events on a specific element, assign it a unique ID using data-aos-id. AOS will then dispatch custom events following the pattern aos:in:[id] and aos:out:[id]:

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

document.addEventListener('aos:in:super-duper', ({ detail }) => {
  console.log('specific element animated in');
});

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

Use AOS API methods: init, refresh, and refreshHard
next
The AOS object provides three primary methods for managing the library state:
- init(): Initializes AOS with the provided settings.
- refresh(): Recalculates all offsets and positions of elements. This is typically called on window resize and is lightweight.
- refreshHard(): Reinitializes the array of AOS elements and triggers a refresh. Use this when the DOM changes significantly (e.g., elements are added/removed asynchronously).
Note: AOS automatically watches for DOM changes using MutationObserver and calls refreshHard() internally. You may need to call AOS.refreshHard() manually in browsers that do not support MutationObserver (like IE).
```
AOS.refresh();
```
https://github.com/michalsnik/aos/blob/next/README.md

Initialize AOS with Global Settings

Call AOS.init() to enable animations. You can pass an optional settings object to configure global behavior.

Global Configuration Options

Option	Type	Default	Description
`disable`	boolean, 'phone', 'tablet', 'mobile', expression, function	`false`	Disables AOS on specific devices or conditions
`startEvent`	string	`'DOMContentLoaded'`	Event name to trigger initialization
`initClassName`	string	`'aos-init'`	Class applied after initialization
`animatedClassName`	string	`'aos-animate'`	Class applied when an element is animating
`useClassNames`	boolean	`false`	If true, adds `data-aos` content as classes on scroll
`disableMutationObserver`	boolean	`false`	Disables automatic mutation detection (advanced)
`debounceDelay`	number	`50`	Delay for window resize debounce (advanced)
`throttleDelay`	number	`99`	Delay for scroll throttle (advanced)
`offset`	number	`120`	Offset (px) from trigger point
`delay`	number	`0`	Delay (0-3000ms, 50ms steps)
`duration`	number	`400`	Duration (0-3000ms, 50ms steps)
`easing`	string	`'ease'`	Default easing function
`once`	boolean	`false`	If true, animation only happens once while scrolling down
`mirror`	boolean	`false`	If true, elements animate out while scrolling past them
`anchorPlacement`	string	`'top-bottom'`	Position of element relative to window to trigger animation

AOS.init({
  disable: false,
  startEvent: 'DOMContentLoaded',
  // ... other settings
  offset: 120,
  duration: 400,
});

Reference: Predefined Animations, Placements, and Easings
next
AOS comes with several built-in options for animations, anchor placements, and easing functions.
Animations
- Fade: fade, fade-up, fade-down, fade-left, fade-right, fade-up-right, fade-up-left, fade-down-right, fade-down-left
- Flip: flip-up, flip-down, flip-left, flip-right
- Slide: slide-up, slide-down, slide-left, slide-right
- Zoom: 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-up, zoom-out-down, zoom-out-left
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
https://github.com/michalsnik/aos/blob/next/README.md

AOS (Animate On Scroll)

What's inside AOS

Example Configuration

CDN Approach

Package Manager Approach

Basic Usage

Advanced Per-Element Customization

Using a Custom Anchor

Custom Animations

Custom Easings

Global Events

Specific Element Events

Global Configuration Options

Animations

Anchor Placements

Easing Functions