| name | scroll-reveal-libraries |
| description | Simple scroll-triggered reveal animations using AOS (Animate On Scroll). Use this skill when building marketing pages, landing pages, or content-heavy sites requiring basic fade/slide effects without complex animation orchestration. Triggers on tasks involving scroll animations, scroll-triggered reveals, AOS, simple animations, or basic scroll effects. Alternative to GSAP ScrollTrigger and Locomotive Scroll for simpler use cases. Compare with motion-framer for React-specific animations. |
Scroll Reveal Libraries
Overview
This skill covers AOS (Animate On Scroll), a lightweight CSS-driven library for scroll-triggered animations. AOS excels at simple fade, slide, and zoom effects activated when elements enter the viewport.
Key Features:
- Minimal Setup: Single JavaScript file + CSS
- Data Attribute API: Configure animations in HTML
- Performance: CSS-driven, GPU-accelerated animations
- 50+ Built-in Animations: Fades, slides, zooms, flips
- Framework Agnostic: Works with vanilla JS, React, Vue, etc.
When to Use:
- Marketing/landing pages with simple scroll effects
- Content-heavy sites (blogs, documentation)
- Quick prototypes requiring scroll animations
- Projects where GSAP/Framer Motion complexity isn't needed
When NOT to Use:
- Complex animation timelines or orchestration → Use GSAP ScrollTrigger
- Physics-based animations → Use React Spring or Framer Motion
- Precise scroll-synced animations → Use GSAP ScrollTrigger
- Heavy interactive animations → Use Framer Motion
Core Concepts
Installation
CDN (Quickest):
<head>
<link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />
</head>
<body>
<script src="https://unpkg.com/aos@next/dist/aos.js"></script>
<script>
AOS.init();
</script>
</body>
NPM/Yarn (Recommended):
npm install aos@next
yarn add aos@next
import AOS from 'aos';
import 'aos/dist/aos.css';
AOS.init();
Basic Usage
Apply animations using the data-aos attribute:
<div data-aos="fade-in">Content</div>
<div data-aos="fade-up">Content</div>
<div data-aos="slide-left">Content</div>
<div data-aos="zoom-in">Content</div>
Configuration Options
Global Configuration:
AOS.init({
duration: 800,
delay: 0,
offset: 120,
easing: 'ease',
once: false,
mirror: false,
anchorPlacement: 'top-bottom',
disable: false,
startEvent: 'DOMContentLoaded',
debounceDelay: 50,
throttleDelay: 99
});
Per-Element Overrides:
<div
data-aos="fade-up"
data-aos-duration="1000"
data-aos-delay="200"
data-aos-offset="50"
data-aos-easing="ease-in-out"
data-aos-once="true"
data-aos-mirror="true"
data-aos-anchor-placement="center-bottom"
>
Custom configured element
</div>
Common Patterns
1. Landing Page Hero Section
<section class="hero">
<h1
data-aos="fade-down"
data-aos-duration="800"
>
Welcome to the Future
</h1>
<p
data-aos="fade-up"
data-aos-delay="200"
data-aos-duration="600"
>
Transform your ideas into reality
</p>
<button
data-aos="zoom-in"
data-aos-delay="400"
data-aos-duration="500"
>
Get Started
</button>
</section>
2. Feature Cards Grid
<div class="features-grid">
<div
class="feature-card"
data-aos="fade-up"
data-aos-duration="600"
data-aos-delay="0"
>
<h3>Feature 1</h3>
<p>Description...</p>
</div>
<div
class="feature-card"
data-aos="fade-up"
data-aos-duration="600"
data-aos-delay="100"
>
<h3>Feature 2</h3>
<p>Description...</p>
</div>
<div
class="feature-card"
data-aos="fade-up"
data-aos-duration="600"
data-aos-delay="200"
>
<h3>Feature 3</h3>
<>Description...
3. Alternating Content Sections
<div class="section">
<div
class="content"
data-aos="slide-right"
data-aos-duration="800"
>
<h2>Section Title</h2>
<p>Content slides in from left...</p>
</div>
<img
src="image1.jpg"
data-aos="fade-left"
data-aos-delay="200"
/>
</div>
<div class="section reverse">
<img
src="image2.jpg"
data-aos="fade-right"
/>
<div
class="content"
data-aos="slide-left"
data-aos-duration="800"
data-aos-delay="200"
>
<h2>Section Title</h2>
<p>Content slides in from right...
4. Scroll-Triggered Testimonials
<div class="testimonials">
<div
class="testimonial"
data-aos="zoom-in"
data-aos-duration="500"
>
<blockquote>"Amazing product!"</blockquote>
<cite>- John Doe</cite>
</div>
<div
class="testimonial"
data-aos="zoom-in"
data-aos-duration="500"
data-aos-delay="100"
>
<blockquote>"Exceeded expectations"</blockquote>
<cite>- Jane Smith</cite>
</div>
</div>
5. Custom Anchor Triggers
Trigger animations based on a different element's scroll position:
<div class="main-content">
<div id="trigger-point" data-aos-id="sidebar-trigger">
</div>
</div>
<aside
class="sidebar"
data-aos="fade-left"
data-aos-anchor="#trigger-point"
>
Sidebar content
</aside>
6. Sequential Animation Chain
<div class="animation-sequence">
<h2
data-aos="fade-down"
data-aos-duration="600"
data-aos-delay="0"
>
Our Process
</h2>
<p
data-aos="fade-up"
data-aos-duration="600"
data-aos-delay="200"
>
Follow these simple steps
</p>
<div
class="process-step"
data-aos="flip-left"
data-aos-delay="400"
>
Step 1
</div>
<div
class="process-step"
data-aos="flip-left"
data-aos-delay="600"
>
Step 2
</div>
<div
class="process-step"
data-aos="flip-left"
data-aos-delay="800"
>
Step 3
</div>
7. Image Gallery with Zoom Effects
<div class="gallery">
<img
src="photo1.jpg"
data-aos="zoom-in-up"
data-aos-duration="800"
/>
<img
src="photo2.jpg"
data-aos="zoom-in-up"
data-aos-duration="800"
data-aos-delay="100"
/>
<img
src="photo3.jpg"
data-aos="zoom-in-up"
data-aos-duration="800"
data-aos-delay="200"
/>
</div>
Integration Patterns
React Integration
Basic Setup:
import { useEffect } from 'react';
import AOS from 'aos';
import 'aos/dist/aos.css';
function App() {
useEffect(() => {
AOS.init({
duration: 800,
once: true,
offset: 100
});
}, []);
return (
<div>
<h1 data-aos="fade-down">Welcome</h1>
<p data-aos="fade-up">Content here</p>
</div>
);
}
Refreshing on Route Changes:
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import AOS from 'aos';
function App() {
const location = useLocation();
useEffect(() => {
AOS.init({ duration: 800 });
}, []);
useEffect(() => {
AOS.refresh();
}, [location]);
return <Routes>{/* routes */}</Routes>;
}
Dynamic Content Updates:
import { useState, useEffect } from 'react';
import AOS from 'aos';
function DynamicList() {
const [items, setItems] = useState([]);
useEffect(() => {
AOS.init();
}, []);
const addItem = () => {
setItems([...items, { id: Date.now(), text: 'New Item' }]);
setTimeout(() => AOS.refresh(), 50);
};
return (
<div>
<button onClick={addItem}>Add Item</button>
<ul>
{items.map((item) => (
<li key={item.id} data-aos="fade-in">
{item.text}
</li>
))}
</ul>
</div>
);
}
Component Wrapper Pattern:
import AOS from 'aos';
import 'aos/dist/aos.css';
function AnimatedSection({ children, animation = "fade-up", delay = 0, ...props }) {
return (
<div
data-aos={animation}
data-aos-delay={delay}
{...props}
>
{children}
</div>
);
}
<AnimatedSection animation="slide-right" delay={200}>
<h2>Animated Content</h2>
</AnimatedSection>
Vue.js Integration
<template>
<div>
<h1 data-aos="fade-down">Vue + AOS</h1>
<div
v-for="(item, index) in items"
:key="item.id"
data-aos="fade-up"
:data-aos-delay="index * 100"
>
{{ item.text }}
</div>
</div>
</template>
<script>
import AOS from 'aos';
import 'aos/dist/aos.css';
export default {
mounted() {
AOS.init({ duration: 800 });
},
updated() {
// Refresh when component updates
this.$nextTick(() => {
AOS.refresh();
});
},
data() {
return {
items: [/*...*/]
};
}
};
</script>
Next.js Integration
import { useEffect } from 'react';
import AOS from 'aos';
import 'aos/dist/aos.css';
function MyApp({ Component, pageProps }) {
useEffect(() => {
AOS.init({
duration: 800,
once: true
});
}, []);
return <Component {...pageProps} />;
}
export default MyApp;
export default function Home() {
return (
<main>
<h1 data-aos="fade-down">Next.js + AOS</h1>
<p data-aos="fade-up">Server-side rendered content with animations</p>
</main>
);
}
Performance Optimization
1. Disable on Mobile Devices
AOS.init({
disable: 'mobile',
disable: function() {
return window.innerWidth < 768;
}
});
2. Use Once for Better Performance
AOS.init({
once: true,
mirror: false
});
3. Optimize Throttle and Debounce
AOS.init({
throttleDelay: 99,
debounceDelay: 50
});
4. Disable Mutation Observer for Static Content
AOS.init({
disableMutationObserver: true
});
5. Reduce Animation Complexity
<div data-aos="fade-in">Simple fade</div>
<div data-aos="flip-left">Complex flip</div>
6. Use RequestIdleCallback for Initialization
if ('requestIdleCallback' in window) {
requestIdleCallback(() => {
AOS.init({ duration: 800 });
});
} else {
AOS.init({ duration: 800 });
}
Common Pitfalls
1. Forgetting to Refresh After DOM Changes
Problem: New elements don't animate after being added dynamically.
Solution: Call AOS.refresh() or AOS.refreshHard():
const newElement = document.createElement('div');
newElement.setAttribute('data-aos', 'fade-in');
container.appendChild(newElement);
AOS.refresh();
AOS.refreshHard();
2. Animations Not Working in React
Problem: AOS doesn't detect elements on first render or route changes.
Solution: Initialize in useEffect and refresh on route/content changes:
useEffect(() => {
AOS.init();
return () => AOS.refresh();
}, []);
useEffect(() => {
AOS.refresh();
}, [location.pathname]);
3. Scroll Performance Issues
Problem: Page scrolling feels janky with many animated elements.
Solution: Reduce animated elements and use once: true:
AOS.init({
once: true,
disable: window.innerWidth < 768
});
4. CSS Conflicts
Problem: Custom CSS interferes with AOS animations.
Solution: Use more specific selectors and avoid !important:
div {
opacity: 1 !important;
}
.my-content > div {
}
5. Anchor Placement Confusion
Problem: Animations trigger at unexpected scroll positions.
Solution: Understand anchor placement options:
data-aos-anchor-placement="top-bottom"
data-aos-anchor-placement="center-center"
data-aos-anchor-placement="bottom-top"
6. Duration/Delay Limits
Problem: Values above 3000ms don't work.
Solution: Add custom CSS for extended durations:
body[data-aos-duration='4000'] [data-aos],
[data-aos][data-aos][data-aos-duration='4000'] {
transition-duration: 4000ms;
}
<div data-aos="fade-in" data-aos-duration="4000">
Long animation
</div>
Built-in Animations
Fade Animations
fade-in - Simple fade infade-up - Fade in from bottomfade-down - Fade in from topfade-left - Fade in from rightfade-right - Fade in from leftfade-up-right - Diagonal fadefade-up-left - Diagonal fadefade-down-right - Diagonal fadefade-down-left - Diagonal fade
Slide Animations
slide-up - Slide from bottomslide-down - Slide from topslide-left - Slide from rightslide-right - Slide from left
Zoom Animations
zoom-in - Zoom inzoom-in-up - Zoom in from bottomzoom-in-down - Zoom in from topzoom-in-left - Zoom in from rightzoom-in-right - Zoom in from leftzoom-out - Zoom outzoom-out-up - Zoom out to topzoom-out-down - Zoom out to bottomzoom-out-left - Zoom out to leftzoom-out-right - Zoom out to right
Flip Animations
flip-up - Flip from bottomflip-down - Flip from topflip-left - Flip from rightflip-right - Flip from left
Custom Animations
Create custom animations with CSS:
[data-aos="custom-slide-bounce"] {
opacity: 0;
transform: translateY(100px);
transition-property: transform, opacity;
}
[data-aos="custom-slide-bounce"].aos-animate {
opacity: 1;
transform: translateY(0);
animation: bounce 0.5s;
}
@keyframes bounce {
0%, 20%, 50%, 80%, 100% {
transform: translateY(0);
}
40% {
transform: translateY(-10px);
}
60% {
transform: translateY(-5px);
}
}
<div data-aos="custom-slide-bounce">
Custom animation
</div>
Comparison with Alternatives
AOS vs GSAP ScrollTrigger
| Feature | AOS | GSAP ScrollTrigger |
|---|
| Complexity | Simple, data-attribute based | Advanced, JavaScript API |
| Use Case | Simple reveals | Complex timelines |
| File Size | ~13KB | ~27KB (GSAP) + ScrollTrigger |
| Performance | CSS-driven | JavaScript-driven |
| Learning Curve | Minutes | Hours |
| Customization | Limited | Extensive |
| Best For | Marketing pages | Interactive experiences |
Use AOS when:
- Simple fade/slide/zoom effects
- Quick implementation needed
- Minimal JavaScript preferred
- Basic scroll reveals sufficient
Use GSAP ScrollTrigger when:
- Complex animation sequences
- Precise scroll-synced animations
- Timeline orchestration needed
- Advanced easing/physics required
Resources
Official Documentation
Key Scripts
scripts/aos_generator.py - Generate AOS HTML boilerplatescripts/config_builder.py - Build AOS configuration
References
references/aos_api.md - Complete AOS API referencereferences/animation_catalog.md - All built-in animations with demosreferences/integration_patterns.md - Framework integration guides
Starter Assets
assets/starter_aos/ - Complete AOS starter templateassets/examples/ - Production-ready patterns
Related Skills
- gsap-scrolltrigger: For complex scroll-driven animations
- motion-framer: For React-specific animations with physics
- locomotive-scroll: For smooth scrolling with parallax
- animated-component-libraries: For pre-built animated React components
