CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-aos

Animate on scroll library that provides CSS3-driven scroll animation effects for web elements

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

AOS (Animate on Scroll)

AOS is a lightweight JavaScript library that enables scroll-triggered CSS3 animations for DOM elements. It provides smooth, performance-optimized animations that trigger when elements enter the viewport, with extensive customization options for timing, easing, and animation types.

Package Information

  • Package Name: aos
  • Package Type: npm
  • Language: JavaScript (ES6+ with Babel transpilation)
  • Installation: npm install aos
  • CDN: Available via CDN for direct browser usage
  • Browser Support: IE10+, all modern browsers

Core Imports

ES6 modules:

import AOS from 'aos';
import 'aos/dist/aos.css'; // Required CSS

CommonJS:

const AOS = require('aos');
require('aos/dist/aos.css'); // Required CSS

Browser (UMD):

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

Basic Usage

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/aos@2.3.4/dist/aos.css" />
</head>
<body>
  <!-- Elements with data-aos attribute will animate -->
  <div data-aos="fade-up">This will fade up when scrolled into view</div>
  <div data-aos="slide-left" data-aos-duration="1000">This will slide left with custom duration</div>
  <div data-aos="zoom-in" data-aos-delay="300">This will zoom in with delay</div>

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

JavaScript usage:

import AOS from 'aos';
import 'aos/dist/aos.css';

// Initialize with default settings
AOS.init();

// Initialize with custom settings
AOS.init({
  duration: 800,
  easing: 'ease-in-out',
  once: true,
  offset: 200
});

// Refresh when content changes
AOS.refresh();

// Hard refresh when DOM structure changes
AOS.refreshHard();

Capabilities

Initialization

Initialize AOS with optional configuration settings.

/**
 * Initialize AOS library with optional configuration
 * @param settings - Configuration object for global animation settings
 * @returns Array of AOS elements that will be animated
 */
AOS.init(settings?: AOSSettings): AOSElement[];

interface AOSSettings {
  /** Trigger distance from bottom of viewport in pixels (default: 120) */
  offset?: number;
  /** Animation delay in milliseconds (default: 0) */
  delay?: number;
  /** Animation duration in milliseconds (default: 400) */
  duration?: number;
  /** CSS easing function (default: 'ease') */
  easing?: string;
  /** Animate only once when scrolling down (default: false) */
  once?: boolean;
  /** Disable conditions - boolean, device type, or function (default: false) */
  disable?: boolean | 'mobile' | 'phone' | 'tablet' | (() => boolean);
  /** Event name for initialization (default: 'DOMContentLoaded') */
  startEvent?: string;
  /** Scroll throttle delay in milliseconds (default: 99) */
  throttleDelay?: number;
  /** Resize debounce delay in milliseconds (default: 50) */
  debounceDelay?: number;
  /** Disable automatic DOM mutation observation (default: false) */
  disableMutationObserver?: boolean;
}

interface AOSElement {
  /** DOM node element */
  node: HTMLElement;
  /** Calculated trigger position */
  position?: number;
}

Refresh Operations

Recalculate element positions and refresh animations.

/**
 * Recalculate all element positions and refresh view
 * Called automatically on window resize
 * @param initialize - Mark library as initialized (internal use)
 * @returns Array of AOS elements or undefined if not initialized
 */
AOS.refresh(initialize?: boolean): AOSElement[] | undefined;

/**
 * Rebuild element array and trigger refresh
 * Use when DOM elements with data-aos are added/removed
 * Called automatically via MutationObserver when supported
 * @returns void
 */
AOS.refreshHard(): void;

HTML Data Attributes

Configure individual elements using data attributes:

interface ElementDataAttributes {
  /** Animation name (required) - see Animation Types */
  'data-aos': string;
  /** Custom offset value in pixels */
  'data-aos-offset'?: string;
  /** Custom duration in milliseconds (50-3000, step 50) */
  'data-aos-duration'?: string;
  /** Custom easing function - see Easing Functions */
  'data-aos-easing'?: string;
  /** Custom delay in milliseconds */
  'data-aos-delay'?: string;
  /** Anchor element selector for trigger calculation */
  'data-aos-anchor'?: string;
  /** Anchor placement position - see Anchor Placement */
  'data-aos-anchor-placement'?: string;
  /** One-time animation override ('true' | 'false') */
  'data-aos-once'?: string;
}

Usage Examples:

<!-- Basic animation -->
<div data-aos="fade-up"></div>

<!-- With custom timing -->
<div data-aos="slide-left" 
     data-aos-duration="1000" 
     data-aos-delay="200"></div>

<!-- With anchor element -->
<div data-aos="zoom-in" 
     data-aos-anchor="#trigger-element" 
     data-aos-anchor-placement="center-bottom"></div>

<!-- Custom easing -->
<div data-aos="flip-right" 
     data-aos-easing="ease-in-out" 
     data-aos-once="true"></div>

Animation Types

Fade Animations

type FadeAnimations = 
  | 'fade'           // Basic fade in/out
  | 'fade-up'        // Fade with upward movement
  | 'fade-down'      // Fade with downward movement
  | 'fade-left'      // Fade with leftward movement
  | 'fade-right'     // Fade with rightward movement
  | 'fade-up-right'  // Fade with diagonal up-right movement
  | 'fade-up-left'   // Fade with diagonal up-left movement
  | 'fade-down-right'// Fade with diagonal down-right movement
  | 'fade-down-left';// Fade with diagonal down-left movement

Flip Animations

type FlipAnimations = 
  | 'flip-up'    // Flip animation upward
  | 'flip-down'  // Flip animation downward
  | 'flip-left'  // Flip animation leftward
  | 'flip-right';// Flip animation rightward

Slide Animations

type SlideAnimations = 
  | 'slide-up'    // Slide animation upward
  | 'slide-down'  // Slide animation downward
  | 'slide-left'  // Slide animation leftward
  | 'slide-right';// Slide animation rightward

Zoom Animations

type ZoomAnimations = 
  | 'zoom-in'         // Zoom in animation
  | 'zoom-in-up'      // Zoom in with upward movement
  | 'zoom-in-down'    // Zoom in with downward movement
  | 'zoom-in-left'    // Zoom in with leftward movement
  | 'zoom-in-right'   // Zoom in with rightward movement
  | 'zoom-out'        // Zoom out animation
  | 'zoom-out-up'     // Zoom out with upward movement
  | 'zoom-out-down'   // Zoom out with downward movement
  | 'zoom-out-left'   // Zoom out with leftward movement
  | 'zoom-out-right'; // Zoom out with rightward movement

Combined Animation Type

type AOSAnimationType = FadeAnimations | FlipAnimations | SlideAnimations | ZoomAnimations;

Anchor Placement Options

Control when animations trigger based on element and viewport positions:

type AnchorPlacement = 
  | 'top-bottom'    // Element top reaches viewport bottom (default)
  | 'top-center'    // Element top reaches viewport center
  | 'top-top'       // Element top reaches viewport top
  | 'center-bottom' // Element center reaches viewport bottom
  | 'center-center' // Element center reaches viewport center
  | 'center-top'    // Element center reaches viewport top
  | 'bottom-bottom' // Element bottom reaches viewport bottom
  | 'bottom-center' // Element bottom reaches viewport center
  | 'bottom-top';   // Element bottom reaches viewport top

Usage Examples:

<!-- Trigger when element top reaches viewport center -->
<div data-aos="fade-in" data-aos-anchor-placement="top-center"></div>

<!-- Trigger when element center reaches viewport bottom -->
<div data-aos="slide-up" data-aos-anchor-placement="center-bottom"></div>

Easing Functions

CSS timing functions for smooth animations:

type EasingFunction = 
  | 'linear'           // Linear timing
  | 'ease'             // Default ease
  | 'ease-in'          // Ease in
  | 'ease-out'         // Ease out
  | 'ease-in-out'      // Ease in and out
  | 'ease-in-back'     // Ease in with back
  | 'ease-out-back'    // Ease out with back
  | 'ease-in-out-back' // Ease in and out with back
  | 'ease-in-sine'     // Ease in sine
  | 'ease-out-sine'    // Ease out sine
  | 'ease-in-out-sine' // Ease in and out sine
  | 'ease-in-quad'     // Ease in quadratic
  | 'ease-out-quad'    // Ease out quadratic
  | 'ease-in-out-quad' // Ease in and out quadratic
  | 'ease-in-cubic'    // Ease in cubic
  | 'ease-out-cubic'   // Ease out cubic
  | 'ease-in-out-cubic'// Ease in and out cubic
  | 'ease-in-quart'    // Ease in quartic
  | 'ease-out-quart'   // Ease out quartic
  | 'ease-in-out-quart';// Ease in and out quartic

CSS Classes

Classes automatically applied by AOS:

interface AOSCSSClasses {
  /** Added to elements during initialization */
  'aos-init': string;
  /** Added/removed to trigger animations */
  'aos-animate': string;
}

Global body attributes set by AOS:

interface GlobalBodyAttributes {
  /** Global easing function applied to body */
  'data-aos-easing': string;
  /** Global duration applied to body */
  'data-aos-duration': string;
  /** Global delay applied to body */
  'data-aos-delay': string;
}

Advanced Configuration

Device-Specific Disabling

// Disable on mobile devices
AOS.init({
  disable: 'mobile'
});

// Disable on phones only
AOS.init({
  disable: 'phone'
});

// Disable on tablets only
AOS.init({
  disable: 'tablet'
});

// Custom disable condition
AOS.init({
  disable: window.innerWidth < 1024
});

// Function-based disable condition
AOS.init({
  disable: function() {
    return window.innerWidth < 1024;
  }
});

Custom Start Events

// Initialize on custom event
AOS.init({
  startEvent: 'load' // Will listen on window instead of document
});

// Custom event name
AOS.init({
  startEvent: 'myCustomEvent'
});

// Trigger custom event
document.dispatchEvent(new Event('myCustomEvent'));

Performance Tuning

AOS.init({
  throttleDelay: 150,      // Increase for better performance
  debounceDelay: 100,      // Increase for better performance
  disableMutationObserver: true // Disable if not needed
});

Custom Duration Ranges

Add custom duration via CSS:

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

Browser Support and Polyfills

AOS includes polyfills for:

  • classlist-polyfill: classList support for older browsers
  • MutationObserver: Automatic graceful degradation for IE9 and below

Unsupported browsers:

  • Internet Explorer 9 and below are automatically disabled
  • Uses browser detection to prevent initialization on unsupported platforms

Error Handling

AOS handles common scenarios automatically:

  • Gracefully degrades when MutationObserver is not supported
  • Automatically disables on unsupported browsers (IE9 and below)
  • Safely handles missing anchor elements
  • Provides console warnings for development debugging

Manual error handling:

// Check if AOS initialized successfully
const elements = AOS.init();
if (elements && elements.length > 0) {
  console.log(`AOS initialized with ${elements.length} elements`);
} else {
  console.log('AOS initialization failed or no elements found');
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/aos@2.3.x
Publish Source
CLI
Badge
tessl/npm-aos badge