در نسخه‌های جدید GSAP (۴ و بالاتر) کتابخانه‌ی رسمی @gsap/react یک هوک سفارشی به نام useGSAP ارائه می‌کند که کار با GSAP در کامپوننت‌های React (به‌ویژه با React 18 و معماری Concurrent) را ساده و ایمن می‌کند.

🔹 نصب

npm install gsap @gsap/react

یا با Yarn:

yarn add gsap @gsap/react

🔸 ایدهٔ اصلی

هوک useGSAP:

• انیمیشن‌های شما را پس از mount شدن عنصر اجرا می‌کند.

• از Context داخلی GSAP استفاده می‌کند تا هنگام unmount شدن کامپوننت، همه انیمیشن‌ها خودکار cleanup شوند (نیازی به دستی پاک کردن نیست).

• شبیه useLayoutEffect عمل می‌کند ولی بهینه‌تر برای GSAP است.

🟢 مثال پایه

import { useRef } from "react";
import gsap from "gsap";
import { useGSAP } from "@gsap/react";

export default function Box() {
  const boxRef = useRef();

  useGSAP(() => {
    gsap.to(boxRef.current, { x: 200, duration: 1 });
  }, []); // [] یعنی فقط یک بار هنگام mount اجرا شود

  return <div ref={boxRef} className="box">Hello GSAP</div>;
}

• تمام انیمیشن‌های تعریف‌شده در کال‌بک useGSAP به‌طور خودکار در context قرار می‌گیرند و هنگام خروج از DOM پاک می‌شوند.

🟡 استفاده از انتخابگر (selector)

useGSAP دومین آرگومان اختیاری می‌گیرد که scope نام دارد؛ این امکان می‌دهد با ()context.selector مثل jQuery انتخاب انجام دهید:

export default function App() {
  const container = useRef();

  useGSAP((context) => {
    const q = context.selector;
    gsap.from(q(".item"), { y: 50, opacity: 0, stagger: 0.2 });
  }, { scope: container });

  return (
    <div ref={container}>
      <div className="item">A</div>
      <div className="item">B</div>
      <div className="item">C</div>
    </div>
  );
}

🟠 Timeline در React

می‌توانید تایم‌لاین را داخل useGSAP بسازید و بعداً آن را کنترل کنید:

export default function Controlled() {
  const box = useRef();
  const tl = useRef();

  useGSAP(() => {
    tl.current = gsap.timeline({ paused: true })
      .to(box.current, { x: 150, duration: 1 })
      .to(box.current, { y: 100, duration: 1 });
  }, []);

  return (
    <>
      <div ref={box} className="box"></div>
      <button onClick={() => tl.current.play()}>Play</button>
      <button onClick={() => tl.current.reverse()}>Reverse</button>
    </>
  );
}

⚡ نکات حرفه‌ای

1. استفاده با ScrollTrigger
   پلاگین‌ها را قبل از استفاده ثبت کنید:

   import { ScrollTrigger } from "gsap/ScrollTrigger";
   gsap.registerPlugin(ScrollTrigger);
   

2. SSR (Next.js / Remix)

   • هوک فقط در سمت کلاینت اجرا می‌شود.

   • اطمینان حاصل کنید که window وجود دارد (کد GSAP را در کامپوننت‌های Client-only بنویسید).

3. تفاوت با useEffect/useLayoutEffect

   • useGSAP خودش از useLayoutEffect استفاده می‌کند و با GSAP Context ادغام شده است.

   • نیازی به return () => ctx.revert() نیست؛ خودکار انجام می‌شود.

✅ خلاصه

• useGSAP → هوک رسمی برای React.

• تمام انیمیشن‌ها را در یک context ایمن اجرا و پاک می‌کند.

• پشتیبانی از selector داخلی و scope برای انتخاب المان‌ها.

• مناسب برای Timeline‌های پیچیده، پلاگین‌هایی مثل ScrollTrigger، و جلوگیری از memory leak.

با این روش، GSAP به‌راحتی در معماری مدرن React (React 18/Next.js) قابل استفاده و مدیریت است.