AOS滚动动画库教程：轻量级CSS驱动，50+内置效果，快速实现滚动触发动画

scroll-reveal-libraries by freshtechbro/claudedesignskills

82 周安装量

11 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/freshtechbro/claudedesignskills --skill scroll-reveal-libraries

开发前端优化动画

🇨🇳中文介绍

滚动显示库

概述

本技能涵盖 AOS（滚动时动画），这是一个轻量级的 CSS 驱动库，用于实现滚动触发的动画。AOS 擅长在元素进入视口时激活简单的淡入淡出、滑动和缩放效果。

主要特性：

极简设置：单个 JavaScript 文件 + CSS
数据属性 API：在 HTML 中配置动画
性能：CSS 驱动，GPU 加速的动画
50+ 内置动画：淡入淡出、滑动、缩放、翻转
框架无关：可与原生 JS、React、Vue 等配合使用

适用场景：

具有简单滚动效果的营销/落地页
内容繁多的网站（博客、文档）
需要滚动动画的快速原型制作
不需要 GSAP/Framer Motion 复杂性的项目

不适用场景：

复杂的动画时间线或编排 → 使用 GSAP ScrollTrigger
基于物理的动画 → 使用 React Spring 或 Framer Motion
精确的滚动同步动画 → 使用 GSAP ScrollTrigger
重度交互式动画 → 使用 Framer Motion

核心概念

安装

CDN（最快）：

<head>
  <link rel="stylesheet" href="https://unpkg.com/aos@next/dist/aos.css" />
</head>
<body>
  <!-- 包含 data-aos 属性的内容 -->

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 落地页英雄区域

<section class="hero">
  <!-- 错开的标题文字 -->
  <h1
    data-aos="fade-down"
    data-aos-duration="800"
  >
    欢迎来到未来
  </h1>

  <!-- 延迟的子标题 -->
  <p
    data-aos="fade-up"
    data-aos-delay="200"
    data-aos-duration="600"
  >
    将您的想法变为现实
  </p>

  <!-- 行动号召按钮 -->
  <button
    data-aos="zoom-in"
    data-aos-delay="400"
    data-aos-duration="500"
  >
    开始使用
  </button>
</section>

2. 功能卡片网格

<div class="features-grid">
  <!-- 使用递增延迟错开卡片 -->
  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    <h3>功能 1</h3>
    <p>描述...</p>
  </div>

  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="100"
  >
    <h3>功能 2</h3>
    <p>描述...</p>
  </div>

  <div
    class="feature-card"
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    <h3>功能 3</h3>
    <p>描述...</p>
  </div>
</div>

3. 交替内容区域

<!-- 内容从左侧进入 -->
<div class="section">
  <div
    class="content"
    data-aos="slide-right"
    data-aos-duration="800"
  >
    <h2>区域标题</h2>
    <p>内容从左侧滑入...</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>区域标题</h2>
    <p>内容从右侧滑入...</p>
  </div>
</div>

4. 滚动触发的推荐语

<div class="testimonials">
  <div
    class="testimonial"
    data-aos="zoom-in"
    data-aos-duration="500"
  >
    <blockquote>"令人惊叹的产品！"</blockquote>
    <cite>- 张三</cite>
  </div>

  <div
    class="testimonial"
    data-aos="zoom-in"
    data-aos-duration="500"
    data-aos-delay="100"
  >
    <blockquote>"超出预期"</blockquote>
    <cite>- 李四</cite>
  </div>
</div>

5. 自定义锚点触发器

根据其他元素的滚动位置触发动画：

<!-- 固定侧边栏根据主内容滚动进行动画 -->
<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"
>
  侧边栏内容
</aside>

<div class="animation-sequence">
  <!-- 步骤 1：标题 -->
  <h2
    data-aos="fade-down"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    我们的流程
  </h2>

  <!-- 步骤 2：描述 -->
  <p
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    遵循这些简单步骤
  </p>

  <!-- 步骤 3-5：流程卡片 -->
  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="400"
  >
    步骤 1
  </div>

  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="600"
  >
    步骤 2
  </div>

  <div
    class="process-step"
    data-aos="flip-left"
    data-aos-delay="800"
  >
    步骤 3
  </div>
</div>

7. 带缩放效果的图片库

<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>

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">欢迎</h1>
      <p data-aos="fade-up">内容在这里</p>
    </div>
  );
}

路由变化时刷新：

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import AOS from 'aos';

function App() {
  const location = useLocation();

  useEffect(() => {
    AOS.init({ duration: 800 });
  }, []);

  // 路由变化时刷新 AOS
  useEffect(() => {
    AOS.refresh();
  }, [location]);

  return <Routes>{/* 路由 */}</Routes>;
}

动态内容更新：

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: '新项目' }]);

    // 刷新 AOS 以检测新元素
    setTimeout(() => AOS.refresh(), 50);
  };

  return (
    <div>
      <button onClick={addItem}>添加项目</button>
      <ul>
        {items.map((item) => (
          <li key={item.id} data-aos="fade-in">
            {item.text}
          </li>
        ))}
      </ul>
    </div>
  );
}

组件包装器模式：

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>动画内容</h2>
</AnimatedSection>

<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() {
    // 组件更新时刷新
    this.$nextTick(() => {
      AOS.refresh();
    });
  },
  data() {
    return {
      items: [/*...*/]
    };
  }
};
</script>

// pages/_app.js
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;

// pages/index.js
export default function Home() {
  return (
    <main>
      <h1 data-aos="fade-down">Next.js + AOS</h1>
      <p data-aos="fade-up">带有动画的服务端渲染内容</p>
    </main>
  );
}

1. 在移动设备上禁用

AOS.init({
  disable: 'mobile', // 在移动设备上禁用
  // 或使用函数进行自定义逻辑
  disable: function() {
    return window.innerWidth < 768;
  }
});

2. 使用 `once` 以获得更好性能

AOS.init({
  once: true, // 仅动画一次（性能更好）
  mirror: false // 不反向动画
});

3. 优化节流和防抖

AOS.init({
  throttleDelay: 99,  // 滚动事件节流（默认）
  debounceDelay: 50   // 调整大小事件防抖（默认）
});

4. 为静态内容禁用 Mutation Observer

AOS.init({
  disableMutationObserver: true // 为完全静态的内容禁用
});

5. 降低动画复杂度

<!-- 更简单的动画性能更好 -->
<div data-aos="fade-in">简单淡入</div>

<!-- 复杂的动画可能导致卡顿 -->
<div data-aos="flip-left">复杂翻转</div>

6. 使用 RequestIdleCallback 进行初始化

if ('requestIdleCallback' in window) {
  requestIdleCallback(() => {
    AOS.init({ duration: 800 });
  });
} else {
  AOS.init({ duration: 800 });
}

1. DOM 更改后忘记刷新

问题：动态添加的新元素没有动画效果。

解决方案：调用 AOS.refresh() 或 AOS.refreshHard()：

// 将元素添加到 DOM 后
const newElement = document.createElement('div');
newElement.setAttribute('data-aos', 'fade-in');
container.appendChild(newElement);

// 刷新 AOS
AOS.refresh(); // 重新计算位置
// 或
AOS.refreshHard(); // 完全重新初始化

2. 在 React 中动画不工作

问题：AOS 在首次渲染或路由变化时未检测到元素。

解决方案：在 useEffect 中初始化并在路由/内容变化时刷新：

useEffect(() => {
  AOS.init();
  return () => AOS.refresh(); // 清理
}, []);

useEffect(() => {
  AOS.refresh(); // 路由变化时刷新
}, [location.pathname]);

3. 滚动性能问题

问题：页面滚动时，由于许多动画元素导致感觉卡顿。

解决方案：减少动画元素并使用 once: true：

AOS.init({
  once: true, // 仅动画一次
  disable: window.innerWidth < 768 // 在移动设备上禁用
});

问题：自定义 CSS 干扰了 AOS 动画。

解决方案：使用更具体的选择器并避免 !important：

/* 不好：与 AOS 冲突 */
div {
  opacity: 1 !important;
}

/* 好：具体的选择器 */
.my-content > div {
  /* 样式 */
}

5. 锚点放置混淆

问题：动画在意外滚动位置触发。

解决方案：理解锚点放置选项：

// 当元素顶部到达视口底部时触发
data-aos-anchor-placement="top-bottom"

// 当元素中心到达视口中心时触发
data-aos-anchor-placement="center-center"

// 当元素底部到达视口顶部时触发
data-aos-anchor-placement="bottom-top"

6. 持续时间/延迟限制

问题：超过 3000 毫秒的值不起作用。

解决方案：添加自定义 CSS 以延长持续时间：

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">
  长动画
</div>

fade-in - 简单淡入
fade-up - 从底部淡入
fade-down - 从顶部淡入
fade-left - 从右侧淡入
fade-right - 从左侧淡入
fade-up-right - 对角线淡入
fade-up-left - 对角线淡入
fade-down-right - 对角线淡入
fade-down-left - 对角线淡入

slide-up - 从底部滑入
slide-down - 从顶部滑入
slide-left - 从右侧滑入
slide-right - 从左侧滑入

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-right - 缩小到右侧

flip-up - 从底部翻转
flip-down - 从顶部翻转
flip-left - 从右侧翻转
flip-right - 从左侧翻转

使用 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">
  自定义动画
</div>

与替代方案的比较

AOS 与 GSAP ScrollTrigger

特性	AOS	GSAP ScrollTrigger
复杂度	简单，基于数据属性	高级，JavaScript API
使用场景	简单显示	复杂时间线
文件大小	~13KB	~27KB (GSAP) + ScrollTrigger
性能	CSS 驱动	JavaScript 驱动
学习曲线	分钟级	小时级
自定义	有限	广泛
最适合	营销页面	交互式体验

使用 AOS 当：

需要简单的淡入淡出/滑动/缩放效果
需要快速实现
倾向于最少的 JavaScript
基本的滚动显示足够

使用 GSAP ScrollTrigger 当：

需要复杂的动画序列
需要精确的滚动同步动画
需要时间线编排
需要高级缓动/物理效果

scripts/aos_generator.py - 生成 AOS HTML 样板文件
scripts/config_builder.py - 构建 AOS 配置

references/aos_api.md - 完整的 AOS API 参考
references/animation_catalog.md - 所有内置动画及演示
references/integration_patterns.md - 框架集成指南

assets/starter_aos/ - 完整的 AOS 入门模板
assets/examples/ - 生产就绪的模式

gsap-scrolltrigger : 用于复杂的滚动驱动动画
motion-framer : 用于具有物理效果的 React 特定动画
locomotive-scroll : 用于带有视差效果的平滑滚动
animated-component-libraries : 用于预构建的动画 React 组件

🇺🇸English

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>
  <!-- Content with data-aos attributes -->

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

NPM/Yarn (Recommended) :

npm install aos@next
# or
yarn add aos@next



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

AOS.init();

Basic Usage

Apply animations using the data-aos attribute:

<!-- Fade in -->
<div data-aos="fade-in">Content</div>

<!-- Fade up -->
<div data-aos="fade-up">Content</div>

<!-- Slide from right -->
<div data-aos="slide-left">Content</div>

<!-- Zoom in -->
<div data-aos="zoom-in">Content</div>

Configuration Options

Global Configuration :

AOS.init({
  // Animation settings
  duration: 800,  // Animation duration (ms): 0-3000
  delay: 0,       // Delay before animation (ms): 0-3000
  offset: 120,    // Offset from trigger point (px)
  easing: 'ease', // Easing function
  once: false,    // Animate only once (true) or every time (false)
  mirror: false,  // Animate out when scrolling past

  // Placement
  anchorPlacement: 'top-bottom', // Which position triggers animation

  // Performance
  disable: false,                // Disable on mobile/tablet
  startEvent: 'DOMContentLoaded', // Initialization event
  debounceDelay: 50,             // Window resize debounce
  throttleDelay: 99              // Scroll throttle
});

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">
  <!-- Staggered heading words -->
  <h1
    data-aos="fade-down"
    data-aos-duration="800"
  >
    Welcome to the Future
  </h1>

  <!-- Delayed subheading -->
  <p
    data-aos="fade-up"
    data-aos-delay="200"
    data-aos-duration="600"
  >
    Transform your ideas into reality
  </p>

  <!-- CTA button -->
  <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">
  <!-- Stagger cards with increasing delays -->
  <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>
    <p>Description...</p>
  </div>
</div>

3. Alternating Content Sections

<!-- Content from left -->
<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>

<!-- Content from right -->
<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...</p>
  </div>
</div>

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:

<!-- Fixed sidebar animates based on main content scroll -->
<div class="main-content">
  <div id="trigger-point" data-aos-id="sidebar-trigger">
    <!-- Content -->
  </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">
  <!-- Step 1: Heading -->
  <h2
    data-aos="fade-down"
    data-aos-duration="600"
    data-aos-delay="0"
  >
    Our Process
  </h2>

  <!-- Step 2: Description -->
  <p
    data-aos="fade-up"
    data-aos-duration="600"
    data-aos-delay="200"
  >
    Follow these simple steps
  </p>

  <!-- Step 3-5: Process cards -->
  <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>
</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 });
  }, []);

  // Refresh AOS on route change
  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' }]);

    // Refresh AOS to detect new elements
    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>
  );
}

// Usage
<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

// pages/_app.js
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;



// pages/index.js
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 on mobile
  // Or use function for custom logic
  disable: function() {
    return window.innerWidth < 768;
  }
});

2. Use Once for Better Performance

AOS.init({
  once: true, // Animate only once (better performance)
  mirror: false // Don't animate out
});

3. Optimize Throttle and Debounce

AOS.init({
  throttleDelay: 99,  // Scroll event throttle (default)
  debounceDelay: 50   // Resize event debounce (default)
});

4. Disable Mutation Observer for Static Content

AOS.init({
  disableMutationObserver: true // Disable for fully static content
});

5. Reduce Animation Complexity

<!-- Simpler animations perform better -->
<div data-aos="fade-in">Simple fade</div>

<!-- Complex animations may cause jank -->
<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():

// After adding elements to DOM
const newElement = document.createElement('div');
newElement.setAttribute('data-aos', 'fade-in');
container.appendChild(newElement);

// Refresh AOS
AOS.refresh(); // Recalculate positions
// or
AOS.refreshHard(); // Reinitialize completely

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(); // Cleanup
}, []);

useEffect(() => {
  AOS.refresh(); // Refresh on route change
}, [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, // Animate only once
  disable: window.innerWidth < 768 // Disable on mobile
});

4. CSS Conflicts

Problem : Custom CSS interferes with AOS animations.

Solution : Use more specific selectors and avoid !important:

/* Bad: Conflicts with AOS */
div {
  opacity: 1 !important;
}

/* Good: Specific selector */
.my-content > div {
  /* styles */
}

5. Anchor Placement Confusion

Problem : Animations trigger at unexpected scroll positions.

Solution : Understand anchor placement options:

// Triggers when element's top hits viewport bottom
data-aos-anchor-placement="top-bottom"

// Triggers when element's center hits viewport center
data-aos-anchor-placement="center-center"

// Triggers when element's bottom hits viewport top
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 in
fade-up - Fade in from bottom
fade-down - Fade in from top
fade-left - Fade in from right
fade-right - Fade in from left
fade-up-right - Diagonal fade
fade-up-left - Diagonal fade
fade-down-right - Diagonal fade
fade-down-left - Diagonal fade

Slide Animations

slide-up - Slide from bottom
slide-down - Slide from top
slide-left - Slide from right
slide-right - Slide from left

Zoom Animations

zoom-in - Zoom in
zoom-in-up - Zoom in from bottom
zoom-in-down - Zoom in from top
zoom-in-left - Zoom in from right
zoom-in-right - Zoom in from left
zoom-out - Zoom out
zoom-out-up - Zoom out to top
zoom-out-down - Zoom out to bottom
zoom-out-left - Zoom out to left
zoom-out-right - Zoom out to right

Flip Animations

flip-up - Flip from bottom
flip-down - Flip from top
flip-left - Flip from right
flip-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

AOS : https://michalsnik.github.io/aos/
GitHub : https://github.com/michalsnik/aos

Key Scripts

scripts/aos_generator.py - Generate AOS HTML boilerplate
scripts/config_builder.py - Build AOS configuration

References

references/aos_api.md - Complete AOS API reference
references/animation_catalog.md - All built-in animations with demos
references/integration_patterns.md - Framework integration guides

Starter Assets

assets/starter_aos/ - Complete AOS starter template
assets/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

Weekly Installs

Repository

freshtechbro/cl…gnskills

GitHub Stars

First Seen

Feb 27, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode82

cursor80

github-copilot80

codex80

amp80

cline80

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

120,000 周安装

AOS滚动动画库教程：轻量级CSS驱动，50+内置效果，快速实现滚动触发动画

🇨🇳中文介绍

滚动显示库

概述

核心概念

安装

相关 Skills

基本用法

配置选项

常见模式