gsap-nuxt-module

Enhance your Nuxt application with powerful animations and transitions using GSAP!

• 📖 Documentation
• 🏀 Online playground
• 📖 GSAP

Features

• Auto-import GSAP: Easily integrate GSAP without manually importing it in every file.
• Dynamic Plugin Registration: Import and register GSAP plugins only if enabled in nuxt.config.ts, optimizing performance.
• Composable for Each Plugin: Use GSAP plugins as composables for a simple and direct experience.

Quick Setup

1. Install the module to your Nuxt application with one command:

 npm i gsap-nuxt-module

2. Add gsap-nuxt-module to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: ['gsap-nuxt-module'],
})

3. Here's how to use GSAP in your component:

<script setup>
const elementRef = ref(null)

onMounted(() => {
  gsap.to(elementRef.value, {
    x: 100
  })
})
</script>

<template>
  <div ref="elementRef">GSAP me!</div>
</template>

Example Configuration

1. In your nuxt.config.ts, enable the desired GSAP plugins:

export default defineNuxtConfig({
  modules: ["gsap-nuxt-module"],
  gsap: {
    plugins: ["Draggable"],
  },
});

2. Here's how to use the Draggable plugin in your component:

<script setup>
const Draggable = useDraggable()

const elementRef = ref(null)

onMounted(() => {
  Draggable.create(elementRef.value)
})
</script>

<template>
  <div ref="elementRef">Drag me!</div>
</template>

You can find more examples in playground

That's it! You can now use gsap-nuxt-module in your Nuxt app ✨

useGsap()

useGsap() returns the GSAP instance directly — use it to access gsap.timeline(), gsap.to(), gsap.set(), utility methods like gsap.utils.toArray(), and more. No import needed; it is auto-imported like all other composables.

<script setup lang="ts">
const gsap = useGsap()
const boxRef = ref(null)

onMounted(() => {
  const tl = gsap.timeline({ repeat: -1, yoyo: true })
  tl.to(boxRef.value, { x: 200, duration: 1, ease: 'power2.inOut' })
    .to(boxRef.value, { rotation: 360, duration: 0.8 })
})
</script>

Context form (recommended)

Pass a setup function to wrap animations in a gsap.context(). The context reverts automatically when the component unmounts — no onUnmounted boilerplate needed. During page navigation, cleanup is deferred until after the leave transition finishes.

<script setup lang="ts">
const containerRef = ref<HTMLElement | null>(null)

useGsap(() => {
  gsap.from('.box', { opacity: 0, y: 30, duration: 0.6 })
}, { scope: containerRef })
</script>

<template>
  <div ref="containerRef">
    <div class="box">I animate in safely</div>
  </div>
</template>

Returns { contextSafe } for wrapping event handlers that add animations after mount. See the full docs for all options.

Available composables

Composable	Plugin	nuxt.config.ts key
useGsap()	GSAP core	— (always available)
useScrollTrigger()	ScrollTrigger	ScrollTrigger
useScrollToPlugin()	ScrollToPlugin	ScrollToPlugin
useScrollSmoother()	ScrollSmoother	ScrollSmoother
useSplitText()	SplitText	SplitText
useScrambleTextPlugin()	ScrambleTextPlugin	ScrambleTextPlugin
useTextPlugin()	TextPlugin	TextPlugin
useDrawSVGPlugin()	DrawSVGPlugin	DrawSVGPlugin
useMorphSVGPlugin()	MorphSVGPlugin	MorphSVGPlugin
useMotionPathPlugin()	MotionPathPlugin	MotionPathPlugin
useMotionPathHelper()	MotionPathHelper	MotionPathHelper
useDraggable()	Draggable	Draggable
useFlip()	Flip	Flip
useInertiaPlugin()	InertiaPlugin	InertiaPlugin
useObserver()	Observer	Observer
usePixiPlugin()	PixiPlugin	PixiPlugin
useEaselPlugin()	EaselPlugin	EaselPlugin
usePhysics2DPlugin()	Physics2DPlugin	Physics2DPlugin
usePhysicsPropsPlugin()	PhysicsPropsPlugin	PhysicsPropsPlugin
useGSDevTools()	GSDevTools	GSDevTools
useCustomEase()	CustomEase	CustomEase
useRoughEase()	RoughEase	RoughEase
useExpoScaleEase()	ExpoScaleEase	ExpoScaleEase
useSlowMo()	SlowMo	SlowMo
useCustomWiggle()	CustomWiggle	CustomWiggle
useCustomBounce()	CustomBounce	CustomBounce

Plugin loading

Only plugins listed in nuxt.config.ts are imported into the generated client plugin. Unused plugins are absent from the build output, and required plugin dependencies are added automatically.

// nuxt.config.ts
export default defineNuxtConfig({
  gsap: {
    plugins: ['ScrollTrigger', 'Draggable'],
    // only these two will be bundled
  },
})

Cleanup

When using useGsap() with a setup function, cleanup is automatic. When using the zero-arg form, use onUnmounted to prevent memory leaks.

Plugin registration is handled once by the module at app startup — never call gsap.registerPlugin() manually. In components, clean up only the instances your component created (tweens, timelines, ScrollTrigger instances, Draggable instances, etc.).

Simple plugin instance cleanup (Draggable):

<script setup lang="ts">
const Draggable = useDraggable()
const boxRef = ref<HTMLElement | null>(null)
let draggables: ReturnType<typeof Draggable.create> = []

onMounted(() => {
  if (!boxRef.value) return
  draggables = Draggable.create(boxRef.value)
})

onUnmounted(() => {
  draggables.forEach((instance) => instance.kill())
  draggables = []
})
</script>

See real cleanup examples in playground/pages/draggable.vue, playground/pages/scroll-trigger.vue, playground/pages/split-text.vue, and playground/pages/scroll-smoother.vue.

Recommended — gsap.context() (covers all child tweens, timelines and ScrollTriggers):

<script setup lang="ts">
const gsap = useGsap()
let ctx: gsap.Context

onMounted(() => {
  ctx = gsap.context(() => {
    gsap.to('.box', { x: 100 })
  })
})

onUnmounted(() => ctx.revert())
</script>

Single timeline:

const gsap = useGsap()
const tl = gsap.timeline()
onUnmounted(() => tl.kill())

→ gsap.context() docs

Contribution

Local development

# Install dependencies
bun install --frozen-lockfile

# Generate type stubs
bun run dev:prepare

# Install Chromium once for browser and page-transition tests
bunx playwright install chromium

# Develop with the playground
bun run dev

# Build the playground
bun run dev:build

# Run ESLint
bun run lint

# Run the complete test suite, or a focused suite
bun run test
bun run test:unit
bun run test:ssr
bun run test:browser
bun run test:watch

# Run the complete release gate
bun run check

# Coverage, bundle budgets, and consumer compatibility
bun run test:coverage
bun run prepack && bun run test:bundle
NUXT_VERSION=3.21.11 bun run test:compat
NUXT_VERSION=4.6.2 bun run test:compat

# Release a semver increment
bun run release:patch
bun run release:minor
bun run release:major