react-gsap-aos

English | 中文文檔

輕量的 GSAP + ScrollTrigger 整合，用法類似 AOS，專為 React / Next.js 設計。

線上展示

專案優勢

• 穩定的效能表現 - 基於 GSAP 與 ScrollTrigger，提供流暢的動畫體驗
• 自動監聽元素變化 - 動態追蹤 DOM 元素的新增與移除，自動註冊動畫（佈局變化需手動呼叫 refreshScrollTrigger）
• 專注高效能實現 - 專注於 AOS 核心功能，沒有多餘的功能負擔
• 完整 TypeScript 支援 - 提供完整的型別定義與型別安全

快速上手

基本使用

"use client";

import { AOSProvider } from "react-gsap-aos/client";
import { toAOSProps } from "react-gsap-aos";

export default function App() {
  return (
    <AOSProvider className="overflow-hidden">
      <div data-aos-container>
        <h1 {...toAOSProps({ animation: "fade-up" })}>Hello World</h1>
      </div>
    </AOSProvider>
  );
}

多個動畫元素

"use client";

import { AOSProvider } from "react-gsap-aos/client";
import { toAOSProps } from "react-gsap-aos";

export default function Demo() {
  return (
    <AOSProvider className="overflow-hidden">
      {/* 有 `data-aos-container`，ScrollTrigger 將使用它作為觸發點 */}
      <div data-aos-container>
        <div {...toAOSProps({ animation: "fade-up", duration: 600 })}>
          第一個區塊
        </div>
      </div>
      {/* 同樣有 `data-aos-container`，即使動畫元素被多層包裹，也會優先使用最接近的容器作為觸發點 */}
      <div data-aos-container>
        <div>
          <div {...toAOSProps({ animation: "fade-up", duration: 600 })}>
            第二個區塊
          </div>
        </div>
      </div>
      {/* 沒有 `data-aos-container`，ScrollTrigger 會自動向上尋找父元素作為觸發點 */}
      <div>
        <div {...toAOSProps({ animation: "zoom-in", delay: 200 })}>
          第三個區塊
        </div>
      </div>
    </AOSProvider>
  );
}

觸發行為說明

1. 自動尋找最接近的 data-aos-container 容器，ScrollTrigger 會用它來量測位置。
2. 如果沒有，就會退回到父元素，都找不到的情況就退回到自身。

注意事項

• 不建議嵌套動畫，雖然仍可注冊，但會因觸發點計算順序導致偏移，需要使用者自行刷新 ScrollTrigger.refresh()。
• 動畫元素仍建議放在單獨容器，以協助正確定位。

動態內容

"use client";

import { useState, useEffect } from "react";
import { AOSProvider, refreshScrollTrigger } from "react-gsap-aos/client";
import { toAOSProps } from "react-gsap-aos";

export default function DynamicList() {
  const [items, setItems] = useState([1, 2, 3]);

  useEffect(() => {
    refreshScrollTrigger();
  }, [items]);

  return (
    <AOSProvider className="overflow-hidden">
      <button onClick={() => setItems([...items, items.length + 1])}>
        新增項目
      </button>
      <ul>
        {items.map((item) => (
          <li key={item} data-aos-container>
            <div {...toAOSProps({ animation: "fade-up" })}>項目 {item}</div>
          </li>
        ))}
      </ul>
    </AOSProvider>
  );
}

API 參考

AOSProvider

為子元素提供動畫範圍的包裝元件

import { AOSProvider } from "react-gsap-aos/client";

<AOSProvider
  component="section"
  className="overflow-hidden"
  options={{
    duration: 600,
    easing: "power2.out",
    once: true,
  }}
>
  {/* 子元素 */}
</AOSProvider>;

屬性

| 名稱 | 型別 | 預設值 | 說明 | | ----------- | --------------------------- | ----------- | ------------------------------------------------ | | component | React.ElementType | 'div' | 要渲染的區塊元素 | | className | string | undefined | 容器的 CSS 類別 | | options | Partial<AnimationOptions> | undefined | 所有子元素的預設動畫選項，下次創建動畫時才會套用 | | children | React.ReactNode | - | 子元素 |

useAOSScope

驅動 AOSProvider 的核心 hook，當需要直接控制容器 ref 時使用

import { useAOSScope } from "react-gsap-aos/client";

function Demo() {
  const { containerRef } = useAOSScope<HTMLDivElement>({
    easing: "bounce.out",
    duration: 800,
  });

  return (
    <div ref={containerRef} className="overflow-hidden">
      <div data-aos="fade-up">動畫內容</div>
    </div>
  );
}

參數

| 名稱 | 型別 | 說明 | | --------- | --------------------------- | ------------------------------------ | | options | Partial<AnimationOptions> | 動畫預設選項，下次創建動畫時才會套用 |

回傳值

| 名稱 | 型別 | 說明 | | -------------- | -------------------- | -------------- | | containerRef | React.RefObject<E> | 容器元素的 ref |

toAOSProps

將動畫選項轉換為 data 屬性

import { toAOSProps } from "react-gsap-aos";

const props = toAOSProps({
  animation: "fade-up",
  duration: 600,
  easing: "power2.out",
});
// 回傳 { "data-aos": "fade-up", "data-aos-duration": 600, ... }

參數

| 名稱 | 型別 | 說明 | | --------- | --------------------------- | -------- | | options | Partial<AnimationOptions> | 動畫選項 |

回傳值

回傳包含 data-aos-* 屬性的物件

refreshScrollTrigger

手動刷新 AOS 動畫位置，封裝自 ScrollTrigger.refresh

import { refreshScrollTrigger } from "react-gsap-aos";

// 在動態 DOM 變更後呼叫
refreshScrollTrigger();

使用時機

當佈局發生變化時需要手動呼叫，以下情況 GSAP 以及該套件已經替你解決

• 視窗大小改變
• 內容高度變化

但是以下情況礙於限制所以需要由使用者主動刷新

• 動態新增或移除非動畫元素

https://gsap.com/docs/v3/Plugins/ScrollTrigger/refresh()

型別定義

AnimationOptions

動畫選項的完整型別定義

interface AnimationOptions {
  animation?: Animation;
  offset?: number;
  delay?: number;
  duration?: number;
  easing?: Easing;
  once?: boolean;
  mirror?: boolean;
  anchorPlacement?: AnchorPlacement;
  markers?: boolean;
}

Animation

支援的動畫類型

• fade, fade-up, fade-down, fade-left, fade-right, fade-up-right,fade-up-left, fade-down-right, fade-down-left
• flip-up, flip-down, flip-left, flip-right
• 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

Easing

支援的緩動函式

• none
• power1, power1.in, power1.out, power1.inOut
• power2, power2.in, power2.out, power2.inOut
• power3, power3.in, power3.out, power3.inOut
• power4, power4.in, power4.out, power4.inOut
• back, back.in, back.out, back.inOut
• bounce, bounce.in, bounce.out, bounce.inOut
• circ, circ.in, circ.out, circ.inOut
• elastic, elastic.in, elastic.out, elastic.inOut
• expo, expo.in, expo.out, expo.inOut
• sine, sine.in, sine.out, sine.inOut

AnchorPlacement

錨點位置類型，格式為 [元素位置]-[視窗位置]

• top-bottom, top-center, top-top
• center-bottom, center-center, center-top
• bottom-bottom, bottom-center, bottom-top

授權

MIT © Gaia Yang;

說明文件以及LLM danielchim

致謝

動畫樣式靈感來自 AOS

由 GSAP 和 ScrollTrigger 驅動