GSAP with Vue, Svelte, and Other Frameworks
Production guide for integrating GSAP into Vue 3, Nuxt 4, Svelte, and other lifecycle-based component frameworks. Covers scoped selectors via gsap.context(), cleanup on unmount, plugin registration, and ScrollTrigger refresh patterns.
For React specifically, use the gsap-react skill (useGSAP hook, gsap.context()). This skill targets non-React frameworks.
When to Use
Apply this skill when:
- Writing or reviewing GSAP code in Vue 3 (Composition API or
<script setup>) or Nuxt 4.
- Writing or reviewing GSAP code in Svelte or SvelteKit.
- The user asks about GSAP with Vue, Svelte, Nuxt,
onMounted, onMount, onDestroy, or component lifecycle animation.
- Scoping GSAP selectors to a component root to avoid cross-component leakage.
- Setting up GSAP plugin registration (ScrollTrigger, SplitText, etc.) in a framework context.
- Cleaning up tweens and ScrollTriggers on component unmount/destroy.
Related skills:
- gsap-core — tweens, basic properties, easing.
- gsap-timeline — timeline construction and sequencing.
- gsap-scrolltrigger — scroll-driven animation, pinning, scrubbing.
- gsap-react — React-specific patterns (useGSAP, contextSafe).
Prerequisites
- GSAP installed in the project:
npm install gsap (or pnpm add gsap, yarn add gsap).
- For Vue: Vue 3.x with Composition API available.
- For Nuxt: Nuxt 4.x project with
composables/ directory support.
- For Svelte: Svelte 4.x or 5.x (lifecycle APIs differ slightly; see Svelte section).
- For ScrollTrigger or other plugins: import from
gsap/<PluginName> and register once at app level.
Windows host note (PowerShell): All CLI commands below assume PowerShell as the default shell. On macOS/Linux, commands are equivalent unless noted.
Procedure
Core Principles (All Frameworks)
- Create tweens and ScrollTriggers after the component's DOM is available (e.g.,
onMounted, onMount).
- Kill or revert them in the unmount (or equivalent) cleanup so nothing runs on detached nodes and there are no leaks.
- Scope selectors to the component root so
.box and similar only match elements inside that component, not the rest of the page.
Vue 3 (Composition API)
- Import
onMounted, onUnmounted, and ref from Vue.
- Import
gsap and any plugins (e.g., ScrollTrigger).
- Register plugins once at app level (e.g., in
main.js), not inside every component.
- In
onMounted, create a gsap.context() with the container ref as scope.
- In
onUnmounted, call ctx.revert().
import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger); // once per app, e.g. in main.js
export default {
setup() {
const container = ref(null);
let ctx;
onMounted(() => {
if (!container.value) return;
ctx = gsap.context(() => {
gsap.to(".box", { x: 100, duration: 0.6 });
gsap.from(".item", { autoAlpha: 0, y: 20, stagger: 0.1 });
}, container.value);
});
onUnmounted(() => {
ctx?.revert();
});
return { container };
},
};
Key points:
gsap.context(callback, scope) — pass container.value as the second argument so selectors like .item are scoped to that root.
- All animations and ScrollTriggers created inside the callback are tracked and reverted when
ctx.revert() is called.
- Always call
ctx.revert() in onUnmounted so tweens and ScrollTriggers are killed and inline styles reverted.
Vue 3 (<script setup>)
Same pattern with <script setup> syntax:
<script setup>
import { onMounted, onUnmounted, ref } from "vue";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
const container = ref(null);
let ctx;
onMounted(() => {
if (!container.value) return;
ctx = gsap.context(() => {
gsap.to(".box", { x: 100 });
gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
}, container.value);
});
onUnmounted(() => {
ctx?.revert();
});
</script>
<template>
<div ref="container">
<div class="box">Box</div>
<div class="item">Item</div>
</div>
</template>
Nuxt 4
- Create a reusable composable at
composables/useGSAP.ts to register GSAP plugins and provide lazy-loading for infrequently used plugins.
- Access
gsap, ScrollTrigger, and lazyLoadPlugin in components via useGSAP().
- Use
gsap.context(scope) and onUnmounted ctx.revert() in components, same as Vue 3.
// composables/useGSAP.ts
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
const PLUGINS = [
"CSSRulePlugin", "CustomBounce", "CustomEase", "CustomWiggle",
"Draggable", "DrawSVGPlugin", "EaselPlugin", "EasePack", "Flip",
"GSDevTools", "InertiaPlugin", "MorphSVGPlugin", "MotionPathHelper",
"MotionPathPlugin", "Observer", "Physics2DPlugin", "PhysicsPropsPlugin",
"PixiPlugin", "ScrambleTextPlugin", "ScrollSmoother", "ScrollToPlugin",
"ScrollTrigger", "SplitText", "TextPlugin",
] as const;
const pluginMap = {
CustomEase: () => import("gsap/CustomEase"),
Draggable: () => import("gsap/Draggable"),
CSSRulePlugin: () => import("gsap/CSSRulePlugin"),
EaselPlugin: () => import("gsap/EaselPlugin"),
EasePack: () => import("gsap/EasePack"),
Flip: () => import("gsap/Flip"),
MotionPathPlugin: () => import("gsap/MotionPathPlugin"),
Observer: () => import("gsap/Observer"),
PixiPlugin: () => import("gsap/PixiPlugin"),
ScrollToPlugin: () => import("gsap/ScrollToPlugin"),
ScrollTrigger: () => import("gsap/ScrollTrigger"),
TextPlugin: () => import("gsap/TextPlugin"),
DrawSVGPlugin: () => import("gsap/DrawSVGPlugin"),
Physics2DPlugin: () => import("gsap/Physics2DPlugin"),
PhysicsPropsPlugin: () => import("gsap/PhysicsPropsPlugin"),
ScrambleTextPlugin: () => import("gsap/ScrambleTextPlugin"),
CustomBounce: () => import("gsap/CustomBounce"),
CustomWiggle: () => import("gsap/CustomWiggle"),
GSDevTools: () => import("gsap/GSDevTools"),
InertiaPlugin: () => import("gsap/InertiaPlugin"),
MorphSVGPlugin: () => import("gsap/MorphSVGPlugin"),
MotionPathHelper: () => import("gsap/MotionPathHelper"),
ScrollSmoother: () => import("gsap/ScrollSmoother"),
SplitText: () => import("gsap/SplitText"),
} as const;
type PluginMap = typeof pluginMap;
type Plugins = keyof PluginMap;
type PluginModule<K extends Plugins> = Awaited<ReturnType<PluginMap[K]>>;
type PluginExport<K extends Plugins> = PluginModule<K>[K & keyof PluginModule<K>];
export default function () {
gsap.registerPlugin(ScrollTrigger);
async function lazyLoadPlugin<K extends Plugins>(plugin: K): Promise<PluginExport<K>> {
const loader = pluginMap[plugin];
const m = await loader();
const p = (m as any)[plugin];
gsap.registerPlugin(p);
return p;
}
return { gsap, ScrollTrigger, lazyLoadPlugin };
}
Access in components:
const { gsap, ScrollTrigger, lazyLoadPlugin } = useGSAP();
useGSAP() provides typed access to the gsap instance and lazy-load method.
- Lazy-load any plugin (SplitText, MorphSVG, etc.) that is not widely used to reduce initial bundle size.
- Use
gsap.context(scope) and onUnmounted ctx.revert() in components, same as Vue 3.
Svelte
- Import
onMount from Svelte.
- Import
gsap and any plugins.
- Use
bind:this={container} to get a reference to the root element.
- In
onMount, create a gsap.context() with the container as scope.
- Return a cleanup function from
onMount that calls ctx.revert().
<script>
import { onMount } from "svelte";
import { gsap } from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
let container;
onMount(() => {
if (!container) return;
const ctx = gsap.context(() => {
gsap.to(".box", { x: 100 });
gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
}, container);
return () => ctx.revert();
});
</script>
<div bind:this={container}>
<div class="box">Box</div>
<div class="item">Item</div>
</div>
bind:this={container} — get a reference to the root element to pass to gsap.context(scope).
return () => ctx.revert() — Svelte's onMount can return a cleanup function; ctx.revert() runs when the component is destroyed.
- Svelte 5 note: Svelte 5 uses a different lifecycle API (runes); the same principle applies: create in mounted and revert in destroyed.
Scoping Selectors
Always pass the scope (container element or ref) as the second argument to gsap.context(callback, scope):
gsap.context(() => { gsap.to(".box", ...) }, containerRef) — .box is only searched inside containerRef.
- Running
gsap.to(".box", ...) without a context scope in a component can affect other instances or the rest of the page.
ScrollTrigger Cleanup and Refresh
- ScrollTrigger instances are created when you use the
scrollTrigger config on a tween/timeline or ScrollTrigger.create().
- They are included in
gsap.context() and reverted when you call ctx.revert().
- Create ScrollTriggers inside the same
gsap.context() callback you use for tweens.
- Call
ScrollTrigger.refresh() after layout changes (e.g., after data loads) that affect trigger positions.
- In Vue: use
nextTick after DOM updates.
- In Svelte: use
tick after DOM updates.
- After async content load: call
ScrollTrigger.refresh() once content is rendered.
When to Create vs Kill
| Lifecycle |
Action |
| Mounted |
Create tweens and ScrollTriggers inside gsap.context(scope). |
| Unmount / Destroy |
Call ctx.revert() so all animations and ScrollTriggers in that context are killed and inline styles reverted. |
Do not create GSAP animations in the component's setup or in a synchronous top-level script that runs before the root element exists. Wait for onMounted / onMount (or equivalent) so the container ref is in the DOM.
Pitfalls
- Creating tweens before mount: Do not create tweens or ScrollTriggers before the component is mounted (e.g., in
setup without onMounted); the DOM nodes may not exist yet.
- Ungscoped selectors: Do not use selector strings without a scope. Always pass the container to
gsap.context() as the second argument so selectors don't match elements outside the component.
- Skipping cleanup: Always call
ctx.revert() in onUnmounted / onMount's return so animations and ScrollTriggers are killed when the component is destroyed. Leaked tweens on detached nodes cause performance degradation and visual bugs.
- Registering plugins per render: Do not register plugins inside a component body that runs every render. It doesn't break anything but is wasteful. Register once at app level (e.g.,
main.js or a Nuxt plugin/composable).
- Forgetting ScrollTrigger.refresh(): After layout changes, image loads, font loads, or async data rendering, trigger positions may be stale. Call
ScrollTrigger.refresh() after the DOM updates.
- Animating pinned trigger elements in ways that invalidate measurements: Avoid animating layout properties (width, height, top, left) on pinned elements; this can cause ScrollTrigger measurement errors.
- Not respecting prefers-reduced-motion: Provide simpler transitions, instant states, or user-controlled playback for users with reduced-motion preference.
Verification
- Check that animations are scoped: Open browser DevTools Console and verify no GSAP inline styles appear on elements outside the component root after mount.
- Check cleanup on unmount: Navigate away from the component (or conditionally destroy it), then run in Console:
ScrollTrigger.getAll().length
The count should not include stale triggers from the unmounted component.
- Check for leaked tweens: After unmount, verify no console errors about tweening detached or null nodes.
- Check ScrollTrigger positions: After layout changes or data loads, run:
ScrollTrigger.refresh()
and verify trigger start/end positions update correctly.
- Check reduced-motion: In DevTools, emulate
prefers-reduced-motion: reduce (Rendering tab in Chrome DevTools) and verify animations degrade gracefully.
- Type check (Nuxt/TS): Run
npx vue-tsc --noEmit in PowerShell to verify the useGSAP composable types resolve correctly.
- Build check: Run
npm run build (or pnpm build) and confirm no GSAP-related import or tree-shaking errors.
Examples
Runnable Projects
- See
examples/vue/ for a runnable Vite + Vue 3 project demonstrating these patterns.
- See
examples/nuxt/ for a runnable Nuxt 4 project with plugin registration, lazy loading, and SSR-safe patterns.
When to load reference files: If the user needs a full project scaffold, read the files under examples/vue/ or examples/nuxt/ to provide copy-pasteable project structure. For plugin-specific API details, refer the user to the gsap-scrolltrigger or gsap-core skills.
Related Skills
- gsap-core — tweens, properties, easing fundamentals.
- gsap-timeline — timeline construction, sequencing, labels.
- gsap-scrolltrigger — scroll-driven animation, pinning, scrubbing, refresh patterns.
- gsap-react — React-specific patterns (useGSAP hook, contextSafe, cleanup).
References
1---
2name: gsap-frameworks
3description: "Integrates GSAP into Vue 3, Nuxt 4, Svelte, and SvelteKit via onMounted/onMount, gsap.context scoped selectors, and ctx.revert() cleanup. Use when writing or reviewing GSAP in those non-React frameworks, including ScrollTrigger plugin registration. Not for React useGSAP/@gsap/react (gsap-web-animations) or GSAP tween/timeline recipes without a component lifecycle."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/gsap-frameworks
7---
8
9# GSAP with Vue, Svelte, and Other Frameworks
10
11Production guide for integrating GSAP into Vue 3, Nuxt 4, Svelte, and other lifecycle-based component frameworks. Covers scoped selectors via `gsap.context()`, cleanup on unmount, plugin registration, and ScrollTrigger refresh patterns.
12
13> **For React specifically**, use the **gsap-react** skill (useGSAP hook, gsap.context()). This skill targets non-React frameworks.
14
15## When to Use
16
17Apply this skill when:
18
19- Writing or reviewing GSAP code in **Vue 3** (Composition API or `<script setup>`) or **Nuxt 4**.
20- Writing or reviewing GSAP code in **Svelte** or **SvelteKit**.
21- The user asks about GSAP with Vue, Svelte, Nuxt, `onMounted`, `onMount`, `onDestroy`, or component lifecycle animation.
22- Scoping GSAP selectors to a component root to avoid cross-component leakage.
23- Setting up GSAP plugin registration (ScrollTrigger, SplitText, etc.) in a framework context.
24- Cleaning up tweens and ScrollTriggers on component unmount/destroy.
25
26**Related skills:**
27
28- **gsap-core** — tweens, basic properties, easing.
29- **gsap-timeline** — timeline construction and sequencing.
30- **gsap-scrolltrigger** — scroll-driven animation, pinning, scrubbing.
31- **gsap-react** — React-specific patterns (useGSAP, contextSafe).
32
33## Prerequisites
34
35- GSAP installed in the project: `npm install gsap` (or `pnpm add gsap`, `yarn add gsap`).
36- For Vue: Vue 3.x with Composition API available.
37- For Nuxt: Nuxt 4.x project with `composables/` directory support.
38- For Svelte: Svelte 4.x or 5.x (lifecycle APIs differ slightly; see Svelte section).
39- For ScrollTrigger or other plugins: import from `gsap/<PluginName>` and register once at app level.
40
41**Windows host note (PowerShell):** All CLI commands below assume PowerShell as the default shell. On macOS/Linux, commands are equivalent unless noted.
42
43## Procedure
44
45### Core Principles (All Frameworks)
46
471. **Create** tweens and ScrollTriggers **after** the component's DOM is available (e.g., `onMounted`, `onMount`).
482. **Kill or revert** them in the **unmount** (or equivalent) cleanup so nothing runs on detached nodes and there are no leaks.
493. **Scope selectors** to the component root so `.box` and similar only match elements inside that component, not the rest of the page.
50
51### Vue 3 (Composition API)
52
531. Import `onMounted`, `onUnmounted`, and `ref` from Vue.
542. Import `gsap` and any plugins (e.g., `ScrollTrigger`).
553. Register plugins once at app level (e.g., in `main.js`), not inside every component.
564. In `onMounted`, create a `gsap.context()` with the container ref as scope.
575. In `onUnmounted`, call `ctx.revert()`.
58
59```javascript
60import { onMounted, onUnmounted, ref } from "vue";
61import { gsap } from "gsap";
62import { ScrollTrigger } from "gsap/ScrollTrigger";
63gsap.registerPlugin(ScrollTrigger); // once per app, e.g. in main.js
64
65export default {
66 setup() {
67 const container = ref(null);
68 let ctx;
69
70 onMounted(() => {
71 if (!container.value) return;
72 ctx = gsap.context(() => {
73 gsap.to(".box", { x: 100, duration: 0.6 });
74 gsap.from(".item", { autoAlpha: 0, y: 20, stagger: 0.1 });
75 }, container.value);
76 });
77
78 onUnmounted(() => {
79 ctx?.revert();
80 });
81
82 return { container };
83 },
84};
85```
86
87**Key points:**
88
89- `gsap.context(callback, scope)` — pass `container.value` as the second argument so selectors like `.item` are scoped to that root.
90- All animations and ScrollTriggers created inside the callback are tracked and reverted when `ctx.revert()` is called.
91- Always call `ctx.revert()` in `onUnmounted` so tweens and ScrollTriggers are killed and inline styles reverted.
92
93### Vue 3 (`<script setup>`)
94
95Same pattern with `<script setup>` syntax:
96
97```vue
98<script setup>
99import { onMounted, onUnmounted, ref } from "vue";
100import { gsap } from "gsap";
101import { ScrollTrigger } from "gsap/ScrollTrigger";
102
103const container = ref(null);
104let ctx;
105
106onMounted(() => {
107 if (!container.value) return;
108 ctx = gsap.context(() => {
109 gsap.to(".box", { x: 100 });
110 gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
111 }, container.value);
112});
113
114onUnmounted(() => {
115 ctx?.revert();
116});
117</script>
118
119<template>
120 <div ref="container">
121 <div class="box">Box</div>
122 <div class="item">Item</div>
123 </div>
124</template>
125```
126
127### Nuxt 4
128
1291. Create a reusable composable at `composables/useGSAP.ts` to register GSAP plugins and provide lazy-loading for infrequently used plugins.
1302. Access `gsap`, `ScrollTrigger`, and `lazyLoadPlugin` in components via `useGSAP()`.
1313. Use `gsap.context(scope)` and `onUnmounted` `ctx.revert()` in components, same as Vue 3.
132
133```typescript
134// composables/useGSAP.ts
135import { gsap } from "gsap";
136import { ScrollTrigger } from "gsap/ScrollTrigger";
137
138const PLUGINS = [
139 "CSSRulePlugin", "CustomBounce", "CustomEase", "CustomWiggle",
140 "Draggable", "DrawSVGPlugin", "EaselPlugin", "EasePack", "Flip",
141 "GSDevTools", "InertiaPlugin", "MorphSVGPlugin", "MotionPathHelper",
142 "MotionPathPlugin", "Observer", "Physics2DPlugin", "PhysicsPropsPlugin",
143 "PixiPlugin", "ScrambleTextPlugin", "ScrollSmoother", "ScrollToPlugin",
144 "ScrollTrigger", "SplitText", "TextPlugin",
145] as const;
146
147const pluginMap = {
148 CustomEase: () => import("gsap/CustomEase"),
149 Draggable: () => import("gsap/Draggable"),
150 CSSRulePlugin: () => import("gsap/CSSRulePlugin"),
151 EaselPlugin: () => import("gsap/EaselPlugin"),
152 EasePack: () => import("gsap/EasePack"),
153 Flip: () => import("gsap/Flip"),
154 MotionPathPlugin: () => import("gsap/MotionPathPlugin"),
155 Observer: () => import("gsap/Observer"),
156 PixiPlugin: () => import("gsap/PixiPlugin"),
157 ScrollToPlugin: () => import("gsap/ScrollToPlugin"),
158 ScrollTrigger: () => import("gsap/ScrollTrigger"),
159 TextPlugin: () => import("gsap/TextPlugin"),
160 DrawSVGPlugin: () => import("gsap/DrawSVGPlugin"),
161 Physics2DPlugin: () => import("gsap/Physics2DPlugin"),
162 PhysicsPropsPlugin: () => import("gsap/PhysicsPropsPlugin"),
163 ScrambleTextPlugin: () => import("gsap/ScrambleTextPlugin"),
164 CustomBounce: () => import("gsap/CustomBounce"),
165 CustomWiggle: () => import("gsap/CustomWiggle"),
166 GSDevTools: () => import("gsap/GSDevTools"),
167 InertiaPlugin: () => import("gsap/InertiaPlugin"),
168 MorphSVGPlugin: () => import("gsap/MorphSVGPlugin"),
169 MotionPathHelper: () => import("gsap/MotionPathHelper"),
170 ScrollSmoother: () => import("gsap/ScrollSmoother"),
171 SplitText: () => import("gsap/SplitText"),
172} as const;
173
174type PluginMap = typeof pluginMap;
175type Plugins = keyof PluginMap;
176type PluginModule<K extends Plugins> = Awaited<ReturnType<PluginMap[K]>>;
177type PluginExport<K extends Plugins> = PluginModule<K>[K & keyof PluginModule<K>];
178
179export default function () {
180 gsap.registerPlugin(ScrollTrigger);
181
182 async function lazyLoadPlugin<K extends Plugins>(plugin: K): Promise<PluginExport<K>> {
183 const loader = pluginMap[plugin];
184 const m = await loader();
185 const p = (m as any)[plugin];
186 gsap.registerPlugin(p);
187 return p;
188 }
189
190 return { gsap, ScrollTrigger, lazyLoadPlugin };
191}
192```
193
194Access in components:
195
196```javascript
197const { gsap, ScrollTrigger, lazyLoadPlugin } = useGSAP();
198```
199
200- `useGSAP()` provides typed access to the gsap instance and lazy-load method.
201- Lazy-load any plugin (SplitText, MorphSVG, etc.) that is not widely used to reduce initial bundle size.
202- Use `gsap.context(scope)` and `onUnmounted` `ctx.revert()` in components, same as Vue 3.
203
204### Svelte
205
2061. Import `onMount` from Svelte.
2072. Import `gsap` and any plugins.
2083. Use `bind:this={container}` to get a reference to the root element.
2094. In `onMount`, create a `gsap.context()` with the container as scope.
2105. Return a cleanup function from `onMount` that calls `ctx.revert()`.
211
212```svelte
213<script>
214 import { onMount } from "svelte";
215 import { gsap } from "gsap";
216 import { ScrollTrigger } from "gsap/ScrollTrigger";
217
218 let container;
219
220 onMount(() => {
221 if (!container) return;
222 const ctx = gsap.context(() => {
223 gsap.to(".box", { x: 100 });
224 gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
225 }, container);
226 return () => ctx.revert();
227 });
228</script>
229
230<div bind:this={container}>
231 <div class="box">Box</div>
232 <div class="item">Item</div>
233</div>
234```
235
236- `bind:this={container}` — get a reference to the root element to pass to `gsap.context(scope)`.
237- `return () => ctx.revert()` — Svelte's `onMount` can return a cleanup function; `ctx.revert()` runs when the component is destroyed.
238- **Svelte 5 note:** Svelte 5 uses a different lifecycle API (runes); the same principle applies: create in mounted and revert in destroyed.
239
240### Scoping Selectors
241
242Always pass the **scope** (container element or ref) as the second argument to `gsap.context(callback, scope)`:
243
244- `gsap.context(() => { gsap.to(".box", ...) }, containerRef)` — `.box` is only searched inside `containerRef`.
245- Running `gsap.to(".box", ...)` without a context scope in a component can affect other instances or the rest of the page.
246
247### ScrollTrigger Cleanup and Refresh
248
249- ScrollTrigger instances are created when you use the `scrollTrigger` config on a tween/timeline or `ScrollTrigger.create()`.
250- They are **included** in `gsap.context()` and reverted when you call `ctx.revert()`.
251- Create ScrollTriggers inside the same `gsap.context()` callback you use for tweens.
252- Call `ScrollTrigger.refresh()` after layout changes (e.g., after data loads) that affect trigger positions.
253 - In Vue: use `nextTick` after DOM updates.
254 - In Svelte: use `tick` after DOM updates.
255 - After async content load: call `ScrollTrigger.refresh()` once content is rendered.
256
257### When to Create vs Kill
258
259| Lifecycle | Action |
260|---|---|
261| **Mounted** | Create tweens and ScrollTriggers inside `gsap.context(scope)`. |
262| **Unmount / Destroy** | Call `ctx.revert()` so all animations and ScrollTriggers in that context are killed and inline styles reverted. |
263
264Do not create GSAP animations in the component's setup or in a synchronous top-level script that runs before the root element exists. Wait for `onMounted` / `onMount` (or equivalent) so the container ref is in the DOM.
265
266## Pitfalls
267
268- **Creating tweens before mount:** Do not create tweens or ScrollTriggers before the component is mounted (e.g., in `setup` without `onMounted`); the DOM nodes may not exist yet.
269- **Ungscoped selectors:** Do not use selector strings without a scope. Always pass the container to `gsap.context()` as the second argument so selectors don't match elements outside the component.
270- **Skipping cleanup:** Always call `ctx.revert()` in `onUnmounted` / `onMount`'s return so animations and ScrollTriggers are killed when the component is destroyed. Leaked tweens on detached nodes cause performance degradation and visual bugs.
271- **Registering plugins per render:** Do not register plugins inside a component body that runs every render. It doesn't break anything but is wasteful. Register once at app level (e.g., `main.js` or a Nuxt plugin/composable).
272- **Forgetting ScrollTrigger.refresh():** After layout changes, image loads, font loads, or async data rendering, trigger positions may be stale. Call `ScrollTrigger.refresh()` after the DOM updates.
273- **Animating pinned trigger elements in ways that invalidate measurements:** Avoid animating layout properties (width, height, top, left) on pinned elements; this can cause ScrollTrigger measurement errors.
274- **Not respecting prefers-reduced-motion:** Provide simpler transitions, instant states, or user-controlled playback for users with reduced-motion preference.
275
276## Verification
277
2781. **Check that animations are scoped:** Open browser DevTools Console and verify no GSAP inline styles appear on elements outside the component root after mount.
2792. **Check cleanup on unmount:** Navigate away from the component (or conditionally destroy it), then run in Console:
280 ```javascript
281 ScrollTrigger.getAll().length
282 ```
283 The count should not include stale triggers from the unmounted component.
2843. **Check for leaked tweens:** After unmount, verify no console errors about tweening detached or null nodes.
2854. **Check ScrollTrigger positions:** After layout changes or data loads, run:
286 ```javascript
287 ScrollTrigger.refresh()
288 ```
289 and verify trigger start/end positions update correctly.
2905. **Check reduced-motion:** In DevTools, emulate `prefers-reduced-motion: reduce` (Rendering tab in Chrome DevTools) and verify animations degrade gracefully.
2916. **Type check (Nuxt/TS):** Run `npx vue-tsc --noEmit` in PowerShell to verify the `useGSAP` composable types resolve correctly.
2927. **Build check:** Run `npm run build` (or `pnpm build`) and confirm no GSAP-related import or tree-shaking errors.
293
294## Examples
295
296### Runnable Projects
297
298- See `examples/vue/` for a runnable Vite + Vue 3 project demonstrating these patterns.
299- See `examples/nuxt/` for a runnable Nuxt 4 project with plugin registration, lazy loading, and SSR-safe patterns.
300
301> **When to load reference files:** If the user needs a full project scaffold, read the files under `examples/vue/` or `examples/nuxt/` to provide copy-pasteable project structure. For plugin-specific API details, refer the user to the **gsap-scrolltrigger** or **gsap-core** skills.
302
303## Related Skills
304
305- **gsap-core** — tweens, properties, easing fundamentals.
306- **gsap-timeline** — timeline construction, sequencing, labels.
307- **gsap-scrolltrigger** — scroll-driven animation, pinning, scrubbing, refresh patterns.
308- **gsap-react** — React-specific patterns (useGSAP hook, contextSafe, cleanup).
309
310## References
311
312- GSAP docs: https://gsap.com/docs/v3/
313- GSAP ScrollTrigger docs: https://gsap.com/docs/v3/Plugins/ScrollTrigger/
314- GSAP context() docs: https://gsap.com/docs/v3/GSAP/gsap.context()
315- Vue 3 Composition API: https://vuejs.org/api/composition-api-lifecycle.html
316- Nuxt 4 composables: https://nuxt.com/docs/guide/directory-structure/composables
317- Svelte onMount: https://svelte.dev/docs/svelte/onMount
318- W3C WCAG 2.2: https://www.w3.org/TR/WCAG22/
319- MDN prefers-reduced-motion: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion