1---
2title: JavaScript Transition Hooks Require done() Callback with css="false"
3impact: HIGH
4impactDescription: Without calling done(), JavaScript-only transitions complete immediately, skipping the animation entirely
5type: gotcha
6tags: [vue3, transition, javascript, animation, hooks, gsap, done-callback]
7---
8 
9# JavaScript Transition Hooks Require done() Callback with css="false"
10 
11**Impact: HIGH** - When using JavaScript-only transitions (with `:css="false"`), the `@enter` and `@leave` hooks **must** call the `done()` callback to signal when the animation completes. Without calling `done()`, Vue considers the transition finished immediately, causing elements to appear/disappear without animation.
12 
13This is especially important when using animation libraries like GSAP, Anime.js, or the Web Animations API.
14 
15## Task Checklist
16 
17- [ ] When using `:css="false"`, always call `done()` in `@enter` and `@leave` hooks
18- [ ] Call `done()` when your JavaScript animation completes (in the `onComplete` callback)
19- [ ] Remember: `done()` is optional when CSS handles the transition, but **required** with `:css="false"`
20- [ ] Use `:css="false"` to prevent CSS rules from interfering with JS animations
21 
22**Problematic Code:**
23```vue
24<template>
25  <!-- BAD: No done() callback - animation is skipped! -->
26  <Transition :css="false" @enter="onEnter" @leave="onLeave">
27    <div v-if="show" class="box">Content</div>
28  </Transition>
29</template>
30 
31<script setup>
32import gsap from 'gsap'
33 
34function onEnter(el) {
35  // Animation starts but Vue doesn't wait for it!
36  gsap.from(el, {
37    opacity: 0,
38    y: 50,
39    duration: 0.5
40  })
41  // Missing done() call - element appears with no animation
42}
43 
44function onLeave(el) {
45  gsap.to(el, {
46    opacity: 0,
47    y: -50,
48    duration: 0.5
49  })
50  // Missing done() call - element removed immediately!
51}
52</script>
53```
54 
55**Correct Code:**
56```vue
57<template>
58  <!-- GOOD: done() callback signals animation completion -->
59  <Transition :css="false" @enter="onEnter" @leave="onLeave">
60    <div v-if="show" class="box">Content</div>
61  </Transition>
62</template>
63 
64<script setup>
65import gsap from 'gsap'
66 
67function onEnter(el, done) {
68  gsap.from(el, {
69    opacity: 0,
70    y: 50,
71    duration: 0.5,
72    onComplete: done  // Tell Vue animation is complete
73  })
74}
75 
76function onLeave(el, done) {
77  gsap.to(el, {
78    opacity: 0,
79    y: -50,
80    duration: 0.5,
81    onComplete: done  // Element removed after animation
82  })
83}
84</script>
85```
86 
87## Why Use `:css="false"`?
88 
891. **Prevents CSS interference**: Vue won't add transition classes that might conflict
902. **Slight performance benefit**: Skips CSS transition detection
913. **Clearer intent**: Makes it explicit that JS controls the animation
92 
93```vue
94<template>
95  <!-- Without :css="false", Vue adds v-enter-active etc. classes -->
96  <!-- These can interfere with your JS animation timing -->
97  <Transition @enter="onEnter" @leave="onLeave">
98    <div v-if="show">May have CSS conflicts</div>
99  </Transition>
100 
101  <!-- With :css="false", no classes added - full JS control -->
102  <Transition :css="false" @enter="onEnter" @leave="onLeave">
103    <div v-if="show">Pure JS animation</div>
104  </Transition>
105</template>
106```
107 
108## Complete JavaScript Transition Example
109 
110```vue
111<template>
112  <Transition
113    :css="false"
114    @before-enter="onBeforeEnter"
115    @enter="onEnter"
116    @after-enter="onAfterEnter"
117    @enter-cancelled="onEnterCancelled"
118    @before-leave="onBeforeLeave"
119    @leave="onLeave"
120    @after-leave="onAfterLeave"
121    @leave-cancelled="onLeaveCancelled"
122  >
123    <div v-if="show" class="animated-box">Content</div>
124  </Transition>
125</template>
126 
127<script setup>
128import gsap from 'gsap'
129import { ref } from 'vue'
130 
131const show = ref(false)
132let enterAnimation = null
133let leaveAnimation = null
134 
135function onBeforeEnter(el) {
136  // Set initial state before animation
137  el.style.opacity = 0
138  el.style.transform = 'translateY(50px)'
139}
140 
141function onEnter(el, done) {
142  // Store animation reference for potential cancellation
143  enterAnimation = gsap.to(el, {
144    opacity: 1,
145    y: 0,
146    duration: 0.5,
147    ease: 'power2.out',
148    onComplete: done  // REQUIRED with :css="false"
149  })
150}
151 
152function onAfterEnter(el) {
153  // Cleanup after enter completes
154  enterAnimation = null
155}
156 
157function onEnterCancelled() {
158  // Handle interruption (e.g., user toggles quickly)
159  if (enterAnimation) {
160    enterAnimation.kill()
161    enterAnimation = null
162  }
163}
164 
165function onBeforeLeave(el) {
166  // Set state before leaving
167}
168 
169function onLeave(el, done) {
170  leaveAnimation = gsap.to(el, {
171    opacity: 0,
172    y: -50,
173    duration: 0.5,
174    ease: 'power2.in',
175    onComplete: done  // REQUIRED with :css="false"
176  })
177}
178 
179function onAfterLeave(el) {
180  leaveAnimation = null
181}
182 
183function onLeaveCancelled() {
184  if (leaveAnimation) {
185    leaveAnimation.kill()
186    leaveAnimation = null
187  }
188}
189</script>
190```
191 
192## Using Web Animations API
193 
194```vue
195<script setup>
196function onEnter(el, done) {
197  const animation = el.animate([
198    { opacity: 0, transform: 'scale(0.9)' },
199    { opacity: 1, transform: 'scale(1)' }
200  ], {
201    duration: 300,
202    easing: 'ease-out'
203  })
204 
205  animation.onfinish = done  // Call done when animation ends
206}
207 
208function onLeave(el, done) {
209  const animation = el.animate([
210    { opacity: 1, transform: 'scale(1)' },
211    { opacity: 0, transform: 'scale(0.9)' }
212  ], {
213    duration: 300,
214    easing: 'ease-in'
215  })
216 
217  animation.onfinish = done
218}
219</script>
220```
221 
222## Common Mistakes
223 
224```javascript
225// WRONG: Calling done() immediately instead of after animation
226function onEnter(el, done) {
227  gsap.from(el, { opacity: 0, duration: 0.5 })
228  done() // Called immediately - animation skipped!
229}
230 
231// WRONG: Forgetting done() parameter
232function onEnter(el) {  // No 'done' parameter
233  gsap.from(el, {
234    opacity: 0,
235    onComplete: done  // Error: done is not defined!
236  })
237}
238 
239// CORRECT: Pass done to animation callback
240function onEnter(el, done) {
241  gsap.from(el, {
242    opacity: 0,
243    duration: 0.5,
244    onComplete: done  // Called after 0.5s
245  })
246}
247```
248 
249## Reference
250- [Vue.js Transition - JavaScript Hooks](https://vuejs.org/guide/built-ins/transition.html#javascript-hooks)
251- [GSAP with Vue](https://gsap.com/resources/vue/)
252