# react-gsap-aos
English | [中文文檔](README.zh-TW.md)
A lightweight GSAP + ScrollTrigger integration with an AOS-like API, specifically designed for React and Next.js applications.
[](https://www.npmjs.com/package/react-gsap-aos)
[](https://opensource.org/licenses/MIT)
[Live Demo](https://react-gsap-aos-nextjs.vercel.app)
## Project Advantages
This is a monorepo managed with pnpm workspaces.
- **Stable Performance** - Built on GSAP and ScrollTrigger, delivers smooth animation experience
- **Automatic Element Tracking** - Dynamically tracks DOM element additions and removals, automatically registers animations (layout changes require manual `refreshScrollTrigger` call)
- **Focused High-Performance Implementation** - Concentrates on core AOS functionality without unnecessary features
- **Full TypeScript Support** - Provides complete type definitions and type safety.
## Quick Start
### Basic Usage
```tsx
"use client";
import { AOSProvider } from "react-gsap-aos/client";
import { toAOSProps } from "react-gsap-aos";
export default function App() {
return (
Hello World
);
}
```
### Multiple Animated Elements
```tsx
"use client";
import { AOSProvider } from "react-gsap-aos/client";
import { toAOSProps } from "react-gsap-aos";
export default function Demo() {
return (
{/* has a data-aos-container, so ScrollTrigger will use it as the trigger. */}
First Block
{/* also has a data-aos-container; even if the animated element is wrapped in multiple layers, the closest container will be used as the trigger. */}
Second Block
{/* no container, so ScrollTrigger automatically searches upward to the parent element for the trigger. */}
Third Block
);
}
```
### Trigger Behavior
1. Automatically find the nearest `data-aos-container`; ScrollTrigger will use it to measure the trigger position.
2. If none exists, it will fall back to the parent element, and if that is also unavailable, it will fall back to the element itself.
#### Notes
- Nested animations are not recommended. They can still be registered, but the trigger calculation order may cause offset issues, so manual `ScrollTrigger.refresh()` may be required.
- It is still recommended to place animation elements in a separate container to ensure correct positioning.
### Dynamic Content
```tsx
"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 (
{items.map((item) => (
Item {item}
))}
);
}
```
## API Reference
### AOSProvider
Wrapper component that provides animation scope for child elements
```tsx
import { AOSProvider } from "react-gsap-aos/client";
{/* Children */}
;
```
**Props**
| Name | Type | Default | Description |
| ----------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| `component` | `React.ElementType` | `'div'` | Block element to render |
| `className` | `string` | `undefined` | CSS class for container |
| `options` | `Partial` | `undefined` | Default animation options for all children, It will be applied the next time the animation is created. |
| `children` | `React.ReactNode` | - | Child elements |
### useAOSScope
Core hook that powers `AOSProvider`, use when you need direct control over container ref
```tsx
import { useAOSScope } from "react-gsap-aos/client";
function Demo() {
const { containerRef } = useAOSScope({
easing: "bounce.out",
duration: 800,
});
return (