or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

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