1---
2title: TransitionGroup Component Best Practices
3impact: MEDIUM
4impactDescription: TransitionGroup animates list items; missing keys or misuse leads to broken list transitions
5type: best-practice
6tags: [vue3, transition-group, animation, lists, keys]
7---
8 
9# TransitionGroup Component Best Practices
10 
11**Impact: MEDIUM** - `<TransitionGroup>` animates lists of items entering, leaving, and moving. Use it for `v-for` lists or dynamic collections where individual items change over time.
12 
13## Task List
14 
15- Use `<TransitionGroup>` only for lists and repeated items
16- Provide unique, stable keys for every direct child
17- Use `tag` when you need semantic or layout wrappers
18- Avoid the `mode` prop (not supported)
19- Use JavaScript hooks for staggered effects
20 
21## Use TransitionGroup for Lists
22 
23`<TransitionGroup>` is designed for list items. Use `tag` to control the wrapper element when needed.
24 
25**BAD:**
26```vue
27<template>
28  <TransitionGroup name="fade">
29    <ComponentA />
30    <ComponentB />
31  </TransitionGroup>
32</template>
33```
34 
35**GOOD:**
36```vue
37<template>
38  <TransitionGroup name="list" tag="ul">
39    <li v-for="item in items" :key="item.id">
40      {{ item.name }}
41    </li>
42  </TransitionGroup>
43</template>
44```
45 
46## Always Provide Stable Keys
47 
48Keys are required. Without stable keys, Vue cannot track item positions and animations break.
49 
50**BAD:**
51```vue
52<template>
53  <TransitionGroup name="list" tag="ul">
54    <li v-for="(item, index) in items" :key="index">
55      {{ item.name }}
56    </li>
57  </TransitionGroup>
58</template>
59```
60 
61**GOOD:**
62```vue
63<template>
64  <TransitionGroup name="list" tag="ul">
65    <li v-for="item in items" :key="item.id">
66      {{ item.name }}
67    </li>
68  </TransitionGroup>
69</template>
70```
71 
72## Do Not Use `mode` on TransitionGroup
73 
74`mode` is only for `<Transition>` because it swaps a single element. Use `<Transition>` if you need in/out sequencing.
75 
76**BAD:**
77```vue
78<template>
79  <TransitionGroup name="list" tag="div" mode="out-in">
80    <div v-for="item in items" :key="item.id">{{ item.name }}</div>
81  </TransitionGroup>
82</template>
83```
84 
85**GOOD:**
86```vue
87<template>
88  <Transition name="fade" mode="out-in">
89    <component :is="currentView" :key="currentView" />
90  </Transition>
91</template>
92```
93 
94## Stagger List Animations with Data Attributes
95 
96For cascading list animations, pass the index to JavaScript hooks and compute delay per item.
97 
98```vue
99<template>
100  <TransitionGroup
101    tag="ul"
102    :css="false"
103    @before-enter="onBeforeEnter"
104    @enter="onEnter"
105  >
106    <li v-for="(item, index) in items" :key="item.id" :data-index="index">
107      {{ item.name }}
108    </li>
109  </TransitionGroup>
110</template>
111 
112<script setup>
113function onBeforeEnter(el) {
114  el.style.opacity = 0
115  el.style.transform = 'translateY(12px)'
116}
117 
118function onEnter(el, done) {
119  const delay = Number(el.dataset.index) * 80
120  setTimeout(() => {
121    el.style.transition = 'all 0.25s ease'
122    el.style.opacity = 1
123    el.style.transform = 'translateY(0)'
124    setTimeout(done, 250)
125  }, delay)
126}
127</script>
128```
129