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>

Available composables

Composable	Plugin	nuxt.config.ts key
useGsap()	GSAP core	— (always available)
useScrollTrigger()	ScrollTrigger	ScrollTrigger
useScrollSmoother()	ScrollSmoother	ScrollSmoother
useSplitText()	SplitText	SplitText
useMotionPathHelper()	MotionPathHelper	MotionPathHelper
useDraggable()	Draggable	Draggable
useFlip()	Flip	Flip
useObserver()	Observer	Observer
useGSDevTools()	GSDevTools	GSDevTools
useCustomEase()	CustomEase	CustomEase
useCustomWiggle()	CustomWiggle	CustomWiggle
useCustomBounce()	CustomBounce	CustomBounce

Plugin loading

Only plugins listed in nuxt.config.ts are dynamically imported — zero bundle overhead for unused plugins.

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

Cleanup

GSAP animations are not automatically cleaned up when a component unmounts. 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
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release