GSAP React Integration (@gsap/react)

Functions executed after the initial useGSAP() call (like click handlers, setTimeout, or event listeners) are not automatically tracked by the GSAP context. To ensure animations created inside these functions are properly scoped and automatically cleaned up when the component unmounts, you must wrap them in contextSafe().

You can access contextSafe in two ways:

1. From the returned object: When calling useGSAP with a config object.
2. As a second argument: Inside the useGSAP() callback function.

Note: If you add event listeners manually inside useGSAP, remember to remove them in the cleanup function returned by the hook.

// Method 1: Using the returned object property
const container = useRef();
const { contextSafe } = useGSAP({ scope: container });

const onClickGood = contextSafe(() => {
    gsap.to(".good", { rotation: 180 });
});

// Method 2: Using the 2nd argument inside useGSAP
useGSAP((context, contextSafe) => {
    const onClickGood = contextSafe(() => {
        gsap.to(".good", { rotation: 180 });
    });
    
    goodRef.current.addEventListener("click", onClickGood);
    
    return () => {
        goodRef.current.removeEventListener("click", onClickGood);
    };
}, { scope: container });

The useGSAP() hook accepts a configuration object as its second argument to provide maximum flexibility.

Key configuration options:

• scope: A React Ref that limits selector text to descendants of that element.
• dependencies: An array of dependencies that trigger the hook.
• revertOnUpdate: A boolean. If true, GSAP objects will be reverted every time the hook updates (when dependencies change). If false (default), they are only reverted when the hook is torn down.

Available method signatures:

• useGSAP(func, config): Most flexible, using a config object.
• useGSAP(func): Simplest form, defaults to an empty dependency array.
• useGSAP(func, dependencies): Similar to useEffect() signature.
• const { context, contextSafe } = useGSAP(config): Returns context and contextSafe for use in event handlers.

// Using the config object for maximum flexibility
useGSAP(() => {
    // gsap code here...
}, { 
    dependencies: [endX], 
    scope: container, 
    revertOnUpdate: true 
});

The useGSAP() hook is the recommended way to use GSAP within React components. It manages GSAP animation lifecycles, handles automatic cleanup (reverting animations) when components unmount or dependencies change, and provides a scoped context for animations.

Signature

useGSAP(callback, dependencies) or useGSAP(config)

Usage Patterns

1. Using a callback and dependency array

Pass a function containing your GSAP code and an optional array of dependencies.

useGSAP(() => {
  gsap.to('.box', { x: 100 });
}, { dependencies: [someVar] });

2. Using a configuration object

You can pass a single object as the argument. This is useful for defining scope and revertOnUpdate.

useGSAP({
  dependencies: [someVar],
  scope: myRef.current,
  revertOnUpdate: true
}, () => {
  gsap.to('.box', { x: 100 });
});

Return Value

The hook returns an object containing:

• context: The GSAP Context instance created for this hook.
• contextSafe: A function used to wrap event handlers or callbacks that should be part of the GSAP context (ensuring they are cleaned up properly).

Configuration Options

• scope: A selector target (like a DOM element or a React Ref) that limits the scope of selector strings used inside the callback.
• dependencies: An array of dependencies that trigger the effect to re-run.
• revertOnUpdate: A boolean determining how cleanup is handled when dependencies change.

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

// Basic usage
useGSAP(() => {
  gsap.to(".box", { rotation: 360 });
});

// Usage with scope and dependencies
const container = useRef();
useGSAP(() => {
  gsap.to(".box", { x: 100 });
}, { dependencies: [someState], scope: container });