Gsap-react NPM

GSAP React

npm

Collection of React utilities and hooks for GSAP.

Installation

Requires gsap version 3.11.0 or newer

npm

npm install gsap-react gsap

yarn

yarn add gsap-react gsap

pnpm

pnpm add gsap-react gsap

Hooks

`useGsapContext`

Memoises a GSAP Context instance.

Usage:

import { useGsapContext } from 'gsap-react'
import { useLayoutEffect, useRef } from 'react'

function App() {
  const ref = useRef<HTMLDivElement>(null)
  const ctx = useGsapContext(ref)

  useLayoutEffect(() => {
    ctx.add(() => {
      gsap.to('.box', {
        x: 200,
        stagger: 0.1,
      })
    })
    return () => ctx.revert()
  }, [])

  return (
    <div className="app" ref={ref}>
      <div className="box">Box 1</div>
      <div className="box">Box 2</div>
      <div className="box">Box 3</div>
    </div>
  )
}

See demo

`useGsapEffect`

Use register effect.

Usage:

import { useGsapEffect } from 'gsap-react'
import { useRef } from 'react'

function App() {
  const box = useRef()
  const animation = useGsapEffect(box, 'spin')

  return <Box ref={box}>Hello</Box>
}

`useSelector`

Query selector

Usage:

import { gsap } from 'gsap'
import { useSelector } from 'gsap-react'
import { useLayoutEffect } from 'react'

function App() {
  const [q, ref] = useSelector<HTMLDivElement>(null)

  useLayoutEffect(() => {
    gsap.to(q('.box'), { x: 200 })
  }, [])

  return (
    <div ref={ref}>
      <div className="box">Box 1</div>
    </div>
  )
}

`useStateRef`

This hook helps solve the problem of accessing stale values in your callbacks. It works exactly like useState, but returns a third value, a ref with the current state.

Usage:

const [count, setCount, countRef] = useStateRef(5)
const [gsapCount, setGsapCount] = useState(0)

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    gsap.to('.box', {
      x: 200,
      repeat: -1,
      onRepeat: () => setGsapCount(countRef.current),
    })
  }, app)
  return () => ctx.revert()
}, [])

See demo

`useMatchMedia`

GSAP MatchMedia

Usage:

import { gsap } from 'gsap'
import { useMatchMedia } from 'gsap-react'
import { useLayoutEffect, useRef } from 'react'

function App() {
  const ref = useRef<HTMLDivElement>(null)
  const mm = useMatchMedia(ref)

  useLayoutEffect(() => {
    mm.add('(min-width: 768px)', () => {
      gsap.to(q('.box'), { x: 200 })
    })

    return () => mm.revert()
  }, [])

  return (
    <div ref={ref}>
      <div className="box">Box 1</div>
    </div>
  )
}

`useMergeRefs`

Merge multiple refs, useful especially when using with forwardRef.

Usage:

import { gsap } from 'gsap'
import { useMergeRefs } from 'gsap-react'
import { forwardRef, useLayoutEffect, useRef } from 'react'

const Button = forwardRef(({ children, ...props }, ref) => {
  const internalRef = useRef<HTMLButtonElement>(null)
  const refs = useMergeRefs(ref, internalRef)

  useLayoutEffect(() => {
    let ctx = gsap.context(() => {}, internalRef)
  }, [])

  return (
    <button ref={refs} {...props}>
      <span className="button-text">{children}</span>
    </button>
  )
})

`useIsomorphicLayoutEffect`

Server side rendering (SSR)

Usage:

import { gsap } from 'gsap'
import { useIsomorphicLayoutEffect } from 'gsap-react'
import { useRef } from 'react'

function App() {
  const app = useRef()

  useIsomorphicLayoutEffect(() => {
    const ctx = gsap.context(() => {
      gsap.from('.box', { opacity: 0 })
    }, app)
    return () => ctx.revert()
  }, [])

  return (
    <div className="app" ref={app}>
      <div className="box">Box 1</div>
    </div>
  )
}

For more information, visit GSAP Hooks.

Components

`SmoothScroll`

This component uses GSAP ScrollSmoother that applies scroll smoothing functionality and easily create elements with different scrolling speed or parallax effects, see docs. Under the hood it register the required plugins gsap.registerPlugin(ScrollTrigger, ScrollSmoother)

🔵 NOTE: This component needs a Club GreenSock membership.

Usage:

import { SmoothScroll } from 'gsap-react'

function App() {
  return (
    <SmoothScroll>
      <div className="box" data-speed={0.6}>
        Box 1
      </div>
      <div className="box" data-speed={0.8}>
        Box 2
      </div>
      <div className="box" data-speed={1.2}>
        Box 3
      </div>
    </SmoothScroll>
  )
}

It accepts options props for customizing the ScrollSmoother. You can also disable the initial wrapper by setting the props noInitialWrapper to true if you plan to create your own wrapper element, just make sure to provide wrapper and content selector inside the options props. default is #smooth-wrapper and #smooth-content.

Usage with NextJS 13.1 app dir:

First create a AppWrapper.tsx and add "use client" directive at the top.

'use client'

import { SmoothScroll } from 'gsap-react'

interface AppWrapperProps {
  children?: React.ReactNode
}

function AppWrapper({ children }: AppWrapperProps) {
  return <SmoothScroll>{children}</SmoothScroll>
}

And import it in your root layout file.

function RootLayout({ children }: { children?: React.ReactNode }) {
  return (
    <html lang="en">
      <head />
      <body>
        <AppWrapper>{children}</AppWrapper>
      </body>
    </html>
  )
}

Usage along side with `ScrollTrigger`:

You may encounter some issues when you have a component that uses ScrollTrigger. To fix this we need to wait for ScrollSmoother plugin to initialize, we can use the useSmoothScroll hook to get the state of the smoother.

'use client'

import { gsap } from 'gsap'
import { useIsomorphicLayoutEffect, useSmoothScroll } from 'gsap-react'
import { useRef } from 'react'

function MyComponent() {
  const { smoother } = useSmoothScroll()

  const ref = useRef<HTMLDivElement>(null)

  useIsomorphicLayoutEffect(() => {
    if (!smoother) return

    let ctx = gsap.context(() => {
      gsap.to('.box', {
        scale: 2,
        scrollTrigger: {
          trigger: ref.current,
        },
      })
    }, ref)

    return () => ctx.revert()
  }, [smoother])

  return (
    <div ref={ref}>
      <div className="box" />
    </div>
  )
}

Don't forget the 'use client' directive when using app dir in NextJS.